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This  volume  describes  the  software  architecture  of  Ptolemy  II.  The  first  chapter  covers  the  kernel 
package,  which  provides  a  set  of  Java  classes  supporting  clustered  graph  topologies  for  models.  Clus¬ 
ter  graphs  provide  a  very  general  abstract  syntax  for  component-based  modeling,  without  assuming  or 
imposing  any  semantics  on  the  models.  The  actor  package  begins  to  add  semantics  by  providing  basic 
infrastructure  for  data  transport  between  components.  The  data  package  provides  classes  to  encapsu¬ 
late  the  data  that  is  transported.  It  also  provides  an  extensible  type  system  and  an  interpreted  expres¬ 
sion  language.  The  graph  package  provides  graph-theoretic  algorithms  that  are  used  in  the  type  system 
and  by  schedulers  in  the  individual  domains.  The  model  transformation  package  provides  a  mechanism 
to  systematically  transform  models  by  means  of  graph  rewriting.  The  plot  package  provides  a  visual 
data  plotting  utility  that  is  used  in  many  of  the  applets  and  applications.  The  codegen  package  is  a  tem- 
plated  based  code  generator  similar  to  the  Ptolemy  Classic  code  generators.  The  copemicus  package  is 
a  code  generator  that  performs  static  analysis  on  Java  class  files  to  produce  smaller,  faster  executable 
models. 

Volume  1  gives  an  introduction  to  Ptolemy  II,  including  tutorials  on  the  use  of  the  software,  and  vol¬ 
ume  3  describes  the  domains,  each  of  which  implements  a  model  of  computation. 
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1.1  Abstract  Syntax 

The  kernel  defines  a  small  set  of  Java  classes  that  implement  a  data  structure  supporting  a  general 
form  of  uninteipreted  clustered  graphs,  plus  methods  for  accessing  and  manipulating  such  graphs. 
These  graphs  provide  an  abstract  syntax  for  netlists,  state  transition  diagrams,  block  diagrams,  etc. 
They  also  provide  the  basic  infrastructure  for  an  an  actor-oriented  version  of  classes,  subclasses,  inner 
classes,  and  inheritance.  An  abstract  syntax  is  a  conceptual  data  organization.  It  can  be  contrasted  with 
a  concrete  syntax,  which  is  a  syntax  for  a  persistent,  readable  representation  of  the  data,  such  as  EDIF 
for  netlists.  A  particular  graph  configuration  is  called  a  topology k 

A  topology  is  a  collection  of  entities  and  relations.  We  use  the  graphical  notation  shown  in  figure 
1.1,  where  entities  are  depicted  as  rounded  boxes  and  relations  as  diamonds.  Entities  have  ports, 
shown  as  filled  circles,  and  relations  connect  the  ports.  We  consistently  use  the  term  connection  to 
denote  the  association  between  connected  ports  (or  their  entities),  and  the  term  link  to  denote  the  asso¬ 
ciation  between  ports  and  relations.  Thus,  a  connection  consists  of  a  relation  and  two  or  more  links. 

We  begin  by  explaining  the  classes  that  support  topologies  with  no  hierarchy,  and  then  show  how 
these  classes  are  extended  to  support  hierarchy. 
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1.2  Non-Hierarchical  Topologies 

The  classes  shown  in  figure  1 .2  support  non-hierarchical  topologies,  like  that  shown  in  figure  1.1. 
Figure  1.2  is  a  UML  static  structure  diagram  (see  appendix  A  of  chapter  1). 

1.2.1  Links 

An  entity  contains  any  number  of  ports;  such  an  aggregation  is  indicated  by  the  association  with  an 
unfilled  diamond  and  the  label  “0..n”  to  show  that  the  entity  can  contain  any  number  of  ports,  and  the 
label  “0..1”  to  show  that  the  port  is  contained  by  at  most  one  entity.  This  association  uses  the  Named- 
List  class  shown  at  the  bottom  of  figure  1.2  and  defined  fully  in  figure  1.4.  There  is  exactly  one 
instance  of  NamedList  associated  with  Entity  used  to  aggregate  the  ports. 

A  port  is  associated  with  any  number  of  relations  (the  association  is  called  a  link),  and  a  relation  is 
associated  with  any  number  of  ports.  Link  associations  use  CrossRefList,  shown  in  figure  1.4.  There  is 
one  instance  of  CrossRefList  associated  with  each  port  and  each  relation.  The  links  define  a  web  of 
interconnected  entities. 

On  the  port  side,  links  have  an  order.  They  are  indexed  from  0  to  n,  where  n  is  the  number  returned 
by  the  numLinks()  method  of  Port. 

1.2.2  Consistency 

A  major  concern  in  the  choice  of  methods  to  provide,  and  in  their  design,  is  maintaining  consis¬ 
tency.  By  consistency  we  mean  that  the  following  key  properties  are  satisfied: 

•  Every  link  between  a  port  an  a  relation  is  symmetric  and  bidirectional.  That  is,  if  a  port  has  a  link 
to  a  relation,  then  the  relation  has  a  link  back  to  that  port. 

•  Every  object  that  appears  on  a  container’s  list  of  contained  objects  has  a  back  reference  to  its  con¬ 
tainer. 

In  particular,  the  design  of  these  classes  ensures  that  the  container  attribute  of  a  port  refers  to  an  entity 
that  includes  the  port  on  its  _portList.  This  is  done  by  limiting  the  access  to  both  attributes.  The  only 
way  to  specify  that  a  port  is  contained  by  an  entity  is  to  call  the  setContainer()  method  of  the  port.  That 
method  guarantees  consistency  by  first  removing  the  port  from  any  previous  container’s  _portList, 
then  adding  it  to  the  new  container’s  port  list.  A  port  is  removed  from  an  entity  by  calling  setCon- 


FIGURE  1.1.  Visual  notation  and  tenninology. 
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tainer()  with  a  null  argument. 

A  change  in  a  containment  association  involves  several  distinct  objects,  and  therefore  must  be 
atomic,  in  the  sense  that  other  threads  must  not  be  allowed  to  intervene  and  modify  or  access  relevant 
attributes  halfway  through  the  process.  This  is  ensured  by  synchronization  on  the  workspace,  as 
explained  below  in  section  1.6.  Moreover,  if  an  exception  is  thrown  at  any  point  during  the  process  of 
changing  a  containment  association,  any  changes  that  have  been  made  are  undone  so  that  a  consistent 
state  is  restored. 
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IntantiableNamedObj 


-_children  :  List 

-  parent :  InstantiableNamedObj 
-JsClassDefintion  :  boolean 
+lnstantiableNamedObj() 

+lnstantiableNamedObj(name :  String) 
+lnstantiableNamedObj(workspace :  Workspace) 
+lnstantiableNamedObj(workspace  :  Workspace,  name  :  String) 
+setClassDefinition(isClassDefinition  :  boolean) 

#_setParent( parent :  InstantiableNamedObj) 


Entity 


-_portList :  NamedList 
+Entity() 

+Entity(name :  String) 

+Entity(workspace :  Workspace) 

+Entity(workspace  :  Workspace,  name  :  String)  0..1 
+connectedPortList() :  List  ♦ 

+connectionsChanged(port :  Port)  conl 

+getPort(name  :  String) :  Port 
+linkedRelationList() :  List 
+newPort(name  :  String) :  Port 
+portList() :  List  1  1 

+removeAIIPorts()  " 

#_addPort(port :  Port) 

#_removePort(port :  Port) 


Port  i.-, 


--Container :  Entity 
#_relationsList :  CrossRefList 
#_insideLinks  :  CrossRefList 
+Port() 

+Port(workspace :  Workspace) 

+Port(container :  Entity,  name  :  String) 
+connectedPortList() :  List  ^ 

+insertLink(int :  index,  relation  :  Relation) _ 

+isLinked(r :  Relation) :  boolean  0..n 

+link(relation  :  Relation) 

+linkedRelationList() :  List 

+linkedRelations() :  Enumeration 

+numLinks() :  int  0..n 

+setContainer( entity :  Entity)  - 

+unlink(index :  int) 

+unlink(relation  :  Relation) 

+unlinkAII() 

#_checkContainer(container :  Entity) 
#_checkLink(relation  :  Relation) 

I 


0..n  containee 


0..n  ports  in  list 


- >' 

1..1  : 


1..1 


Relation 


- _ linkList :  CrossRefList 

+Relation() 

+Relation(name :  String) 

+Relation(w :  Workspace,  name  :  String) 
+Relation(w :  Workspace) 

+link(relation  :  Relation) 
+linkedObjectsList() :  List 
+linkedPortList() :  List 
+linkedPortList(except :  Port) :  List 
+numLinks() :  int 
+relationGroupList() :  List 
+unlink( relation  :  Relation) 

+unlinkAII() 

#_checkPort(port :  Port) 
#_checkRelation(relation  :  Relation) 


port  list 


1..1 


FIGURE  1 .2.  Key  classes  in  the  kernel  package  and  their  methods  supporting  basic  (non-hierarchical)  topol¬ 
ogies.  Methods  that  override  those  defined  in  a  base  class  or  implement  those  in  an  interface  are  not  shown. 
The  “+”  indicates  public  visibility,  “#”  indicates  protected,  and  indicates  private.  Capitalized  methods  are 
constructors.  The  classes  and  interfaces  shown  with  dashed  outlines  are  in  the  kemel.util  subpackage. 
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1.3  Support  Classes 

The  kernel  package  has  a  subpackage  called  kemel.util  that  provides  the  key  base  class  for  almost 
all  Ptolemy  II  objects,  NamedObj,  shown  in  figure  1.3.  This  class  defines  notions  basic  to  Ptolemy  II 
(containment,  naming,  parameterization,  and  inheritance)  and  provides  generic  support  for  relevant 
data  structures.  Although  nominally  the  Nameable  interface  is  what  defines  the  naming  and  contain¬ 
ment  relationships,  in  practice,  much  of  Ptolemy  II  relies  on  implementations  of  Nameable  being 
instances  of  NamedObj. 

1.3.1  Containers 

Although  NamedObj  does  not  provide  support  for  constructing  clustered  graphs,  it  provides  rudi¬ 
mentary  support  for  container  associations.  An  instance  can  have  at  most  one  container.  That  container 
is  viewed  as  the  owner  of  the  object,  and  “managed  ownership”  [75]  is  used  as  a  central  tool  in  thread 
safety,  as  explained  in  section  1.6  below. 

In  the  base  classes  shown  in  figure  1 .2,  only  an  instance  of  Port  can  have  a  non- null  container.  It  is 
the  only  class  with  a  setContainer()  method.  Instances  of  all  other  classes  shown  have  no  container, 
and  their  getContainer()  method  will  return  null.  Below  we  will  discuss  derived  classes  that  have  con¬ 
tainers. 

Every  object  is  associated  with  exactly  one  instance  of  Workspace,  as  shown  in  figure  1.4,  but  the 
workspace  is  not  viewed  as  a  container.  A  workspace  is  specified  when  an  object  is  constructed,  and  no 
methods  are  provided  to  change  it.  It  is  said  to  be  immutable,  a  critical  property  in  its  use  for  thread 
safety.  An  object  with  a  container  always  inherits  its  workspace  from  the  container. 

1.3.2  Name  and  Full  Name 

The  Nameable  interface  shown  in  figure  1.3  supports  hierarchy  in  the  naming  so  that  individual 
named  objects  in  a  hierarchy  can  be  uniquely  identified.  By  convention,  the  full  name  of  an  object  is  a 
concatenation  of  the  full  name  of  its  container,  if  there  is  one,  a  period  and  the  name  of  the 
object.  The  full  name  is  used  extensively  for  error  reporting.  A  top-level  object  always  has  a  period  as 
the  first  character  of  its  full  name.  The  full  name  is  returned  by  the  getFullName()  method  of  the 
Nameable  interface. 

NamedObj  is  a  concrete  class  implementing  the  Nameable  interface.  It  also  serves  as  an  aggrega¬ 
tion  of  attributes,  as  explained  below  in  section  1.3.4.  It  supports  inheritance  (via  its  implementation  of 
the  Derivable  interface),  persistence  (via  the  MoMLExportable  interface),  debugging  (via  the  Debug- 
gable  interface),  and  mutations  (via  the  Changeable  interface). 

Names  of  objects  are  only  required  to  be  unique  within  a  container.  Thus,  even  the  full  name  is  not 
assured  of  being  globally  unique. 

Here,  names  are  a  property  of  the  instances  themselves,  rather  than  properties  of  an  association 
between  entities.  As  argued  by  Rumbaugh  in  [138],  this  is  not  always  the  right  choice.  Often,  a  name  is 
more  properly  viewed  as  a  property  of  an  association.  For  example,  a  file  name  is  a  property  of  the 
association  between  a  directory  and  a  file.  A  file  may  have  multiple  names  (through  the  use  of  sym¬ 
bolic  links).  Our  design  takes  a  stronger  position  on  names,  and  views  them  as  properties  of  the  object, 
much  as  we  view  the  name  of  a  person  as  a  property  of  the  person  (vs.  their  employee  number,  for 
example,  which  is  a  property  of  their  association  with  an  employer). 
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+CLASSNAME 

:  int 

+COMPLETE  : 

int 

+CONTENTS  : 

int 

+DEEP  :  int 

+FULLNAME  : 

int 

l+LINKS  :  int 

#_changeListeners  :  List 
#_changeLock  :  Object 
#_changeRequests  :  List 
#_debugging  :  boolean 
#_debugListeners  :  LinkedList 
#_elementName  :  String 
#_isPersistent :  boolean 
#_workspace  :  Workspace 
-_attributes  :  NamedList 
-_className  :  String 
-  DEFAULT  WORKSPACE  :  Workspace 


-_deferChangeRequests  :  boolean 
-_derived Level :  int 

-jnodelErrorHandler :  ModelErrorHandler 
-_name  :  String 
-_override  :  List 
-_source  :  String 


NamedObi 


+ ATTRIBUTES  :  int 


«lnterface» 

Derivable 


+getDerivedLevel()  :  int 
+getDerivedList() :  List 
+getPrototypeList()  :  List 
propagateValue()  :  List 
propagateExistence() :  Listl 


+NamedObj() 

+NamedObj(name  :  String) 

+NamedObj(w  :  Workspace) 

+NamedObj(w  :  Workspace,  name  :  String) 
+attributeChanged(a  :  Attribute) 

+attributeList() :  List 
+attributeList(filter :  Class) :  List 
+attributeTypeChanged(a  :  Attribute) 

+clone(destination  :  Workspace) :  Object 
+containedObjectslterator() :  Iterator 
+deepContains(inside  :  NamedObj) :  boolean 
+depthlnHierarchy()  :  int 
+description(detail  :  int) :  String 
+getAttribute(name  :  String)  :  Attribute 
+getAttribute(name  :  String,  c  :  Class)  :  Attribute 
+getChangeListeners() :  List 
+getModelErrorHandler()  :  ModelErrorHandler 
+isOverridden() :  boolean 
+message(message  :  String) 

+propagateValues() 

+setClassName(name  :  String) 

+setDerivedLevel(level :  int) 

+setModelErrorHandler(handler :  ModelErrorHandler) 
+toplevel() :  NamedObj 
+uniqueName(prefix  :  String)  :  String 
+validateSettables() 

+workspace()  :  Workspace 
#_addAttribute(attribute  :  Attribute) 

#_attachText(name  :  String,  text :  String) 
#_cloneFixAttributeFields(n  :  NamedObj) 

#_debug(event :  DebugEvent) 

#_debug(message  :  String) 

#_debug(part1  :  String,  part2  :  String) 

#_debug(part1  :  String,  part2  :  String,  part3  :  String) 
#_debug(p1  :  String,  p2  :  String,  p3  :  String,  p4  :  String) 
#_description(detail :  int,  indent :  int,  bracket :  int) :  String 
#_exportMoMLContents(output :  Writer,  depth  :  int) 
#_getContainedObject(c  :  NamedObj,  n  :  String) :  NamedObj| 
#_getlndentPrefix(depth  :  int)  :  String 
#_isMoMLSuppressed(depth  :  int) :  boolean 
#_markContentsDerived(depth  :  int) 
#_propagateExistence(container :  NamedObj) 
#_propagateValue(destination  :  NamedObj) 
#_removeAttribute(attribute  :  Attribute) 

#_splitName(name  :  String)  :  String[] 
#_stripNumericSuffix(name  :  String) :  String 


A 


-CH 


s3 


«lnterface» 

Instantiable 


+getChildren() :  List 
+getParent() :  Instantiable 
+instantiate() :  Instantiable 
+isClassDefinition() :  boolean 


«lnterface» 

Nameable 


+description() :  String 
+getContainer() :  NamedObj 
+getFullName() :  String 
+getName() :  String 

+getName(relativeTo  :  NamedObj)  :  String 
+setName(name  :  String) 
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+exportMoML() :  String 
+exportMoML(replacementName  :  String) 

+exportMoML(output :  Writer) 

+exportMoML(output :  Writer,  depth  :  int) 

+exportMoML(output :  Writer,  depth  :  int,  replacementName  :  String) 

+getClassName() :  String 

+getElementName()  :  String 

+getSource() :  String 

+isPersistent() :  boolean 

+setPeristent(isPersistent :  boolean) 

+setSource(source  :  String) 


— ■ -O 


--o 


«lnterface» 

MoMLExportab/e 


Debuggable 


+addDebugListener(listener :  DebugListener) 
removeDebugListener(listener :  DebugListener) 


«lnterface» 

Changeable 


+addChangeListener(listener :  ChangeListener) 
+executeChangeRequests() 
isDeferringChangeRequests()  :  boolean 
+removeChangeListener(listener :  ChangeListener) 
requestChange(change  :  ChangeRequest) 
+setDeferringChangeRequests(isDeferring  :  boolean) 


«lnterface» 

DebugListener 


+event(event :  DebugEvent) 
+message(message :  String)\ 


«lnterface» 

DebugEvent 


+getSource() :  NamedObj 
+toString() :  String 


StreamListener 


+StreamListener() 

+StreamListener(stream  :  OutputStream)! 


RecorderListener 


+RecorderListener() 
+getMessages()  :  String 
+reset() 


«lnterface» 

ModelErrorHandler 


+handleModelError(context :  NamedObj,  exception  :  INegalActionException) 


FIGURE  1 .3.  Support  classes  in  the  kernel.util  package. 
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1.3.3  Workspace 

Workspace  is  a  concrete  class  that  implements  the  Nameable  interface,  as  shown  in  figure  1.4.  All 
objects  in  a  Ptolemy  II  model  are  associated  with  a  workspace,  and  almost  all  operations  that  involve 
multiple  objects  are  only  supported  for  objects  in  the  same  workspace.  This  constraint  is  exploited  to 
ensure  thread  safety,  as  explained  in  section  1.6  below. 

1.3.4  Attributes 

In  almost  all  applications  of  Ptolemy  II,  entities,  ports,  and  relations  need  to  be  parameterized.  An 
instance  of  NamedObj  (figure  1.3)  can  have  any  number  of  instances  of  the  Attribute  class  attached  to 
it,  as  shown  in  figure  1.5.  Attribute  is  a  NamedObj  that  can  be  contained  by  another  NamedObj,  and 
serves  as  a  base  class  for  parameters. 

Attributes  are  added  to  a  NamedObj  by  calling  their  setContainer()  method  and  passing  it  a  refer¬ 
ence  to  the  container.  Alternatively,  the  container  can  be  given  as  a  constructor  argument.  They  are 


«utility» 

NamedList 


_container :  Nameable 
_namedlist :  LinkedList 


+NamedList() 

+NamedList(container :  Nameable) 
+NamedList(original :  NamedList) 
+append(element :  Nameable) 

+clone()  :  Object 

+elementList() :  List 

+first() :  Nameable 

+get(name  :  String)  :  Nameable 

+includes(element :  Nameable) :  boolean 

+insertAfter(name  :  String,  element :  Nameable) 

+insertBefore(name  :  String,  element :  Nameable) 

+last() :  Nameable 

+prepend(element :  Nameable) 

+remove(element :  Nameable) 

+remove(name  :  String)  :  Nameable 
+removeAII() 

+size() :  int 


«lnterface» 

Nameable 


j-_workspace  :  Workspace  : 
-attributes  :  NamedList 
|+workspace()  :  Workspace- 


|-_directory :  LinkedList 
name  :  String 
.readers  :  Hashtable 
.readonly  :  boolean 
writer :  Thread 


|+addDebugListener(listener :  DebugListener) 
:+removeDebugListener(listener :  DebugListener) 


«utility» 

CrossRefList.CrossRef 


■_far :  CrossRef 
-_next :  CrossRef 
-_previous  :  CrossRef 


CrossRef() 

CrossRef(other :  CrossRef) 
CrossRef(index  :  int) 
_nearContainer() :  Object 
_farContainer()  :  Object 
_nearList() :  CrossRefList 
_dissociate() 

_unlink() 


container :  Object 
headNode  :  CrossRef 
lastNode  :  CrossRef 


+CrossRefList(container :  Object) 
+CrossRefList(container :  Object,  o  :  CrossRefList) 
+first() :  Object 
+get(index  :  int) :  Object 
+getContainers()  :  Enumeration 
+insertLink(index  :  int,  farList :  CrossRefList) 
+isLinked(object :  Object)  :  boolean 
+link(farList :  CrossRefList) 

+size() :  int 
+unlink(index  :  int) 

+unlink(object :  Object) 

+unlinkAII() 


Workspace 


+Workspace() 

+Workspace(name  :  String) 

+add(item  :  NamedObj) 

+description(detail  :  int)  :  String 
+directoryList() :  List 
+doneReading() 

+doneWriting() 

+getReadAccess() 

+getVersion() :  long 
+getWriteAccess() 

+incrVersion() 

+isReadOnly()  :  boolean 
+remove(item  :  NamedObj) 

+removeAII() 

+setReadOnly(b  :  boolean) 

+wait(obj :  Object) 

|#_description(detail :  int,  indent :  int,  bracket :  int)  :  String 


PtolemyThread 


+PtolemyThread() 

+PtolemyThread(target :  Runnable) 

+PtolemyThread(target :  Runnable,  name  :  String) 
+PtolemyThread(name  :  String) 

+PtolemyThread(group  :  ThreadGroup,  target :  Runnable) 
+PtolemyThread(group  :  ThreadGroup,  target :  Runnable,  name  :  String) 
+PtolemyThread(group  :  ThreadGroup,  name  :  String) 


FIGURE  1 .4.  Some  key  utility  classes.  Workspace  is  the  key  gatekeeper  class  supporting  multithreaded 
access  to  Ptolemy  II  models.  It  supports  exclusive  write  access  and  shared  read  access.  Every  instance  of 
NamedObj  is  associated  with  exactly  one  instance  of  Workspace.  NamedList  is  a  utility  class  used  for  lists  of 
instances  of  NamedObj.  CrossRefList  manages  cross  references  that  must  be  kept  consistent. 
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FIGURE  1.5.  An  instance  of  NamedObj  can  contain  any  number  of  instances  of  Attribute.  The  Ptolemy  II 
kernel  provides  a  few  basic  attributes,  as  shown  here.  Attributes  that  have  values  implement  the  Settable  inter¬ 
face.  Attributes  whose  values  are  numeric  data,  expressions,  or  data  structures  are  described  in  the  Data  Pack¬ 
age  chapter. 
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removed  by  calling  setContainer()  with  a  null  argument.  The  NamedObj  class  provides  the  getAt- 
tribute()  method,  which  takes  an  attribute  name  as  an  argument  and  returns  the  attribute,  and  the 
attributeList()  method,  which  returns  a  list  of  the  attributes  contained  by  the  object.  Both  of  these 
methods  have  versions  that  also  takes  a  Class  argument,  and  returns  only  attributes  that  are  instances  of 
the  specified  Java  class. 

By  itself,  an  instance  of  the  Attribute  class  carries  only  a  name,  which  may  not  be  sufficient  to 
parameterize  objects.  Several  derived  classes  implement  the  Settable  interface,  which  indicates  that 
they  can  be  assigned  a  value  via  a  string.  A  simple  attribute  implementing  the  Settable  interface  is  the 
StringAttribute.  It  has  a  value  that  can  be  any  string.  A  more  sophisticated  parameter  called  StringPa- 
rameter  is  defined  in  the  data  package  and  has  a  value  that  is  a  string  that  can  include  references  to 
other  parameter  values.  A  derived  class  called  Variable  that  implements  the  Settable  interface  is 
defined  in  the  data  package.  The  value  of  an  instance  of  Variable  is  typically  an  arithmetic  expression. 
The  Variable  class  is  described  in  the  Data  chapter. 

Some  attributes  are  configurable,  which  means  that  their  value  is  set  via  (typically  XML)  text  that 
is  nested  in  a  MoML  configure  tag.  See  the  MoML  chapter  for  details.  An  attribute  that  is  not  an 
instance  of  Settable  or  Configurable  is  called  a  pure  attribute.  Its  mere  presence  has  significance. 

Attribute  names  can  be  any  string  that  does  not  include  periods,  but  it  is  recommend  to  stick  to 
alphanumeric  characters,  the  space  character,  and  the  underscore.  Names  beginning  with  an  underscore 
are  reserved  for  system  use.  The  following  names,  for  example,  are  in  use: 


Table  l.l:Names  of  special  attributes 


name 

class 

use 

createdBy 

ptolemy.kemel.util.VersionAttribute 

Version  of  Ptolemy  II  that  last  wrote  the  file. 

doc 

ptolemy.actor.gui. Documentation 

Default  documentation  attribute  name. 

generator 

ptolemy.codegen.gui.GeneratorTableauAttribute 

Parameters  for  code  generators. 

icon 

ptolemy.  vergil .  toolbox.  Editorlcon 

Icon  renderer  attribute. 

iconDescription 

ptolemy.kemel.util.  StringAttribute 

XML  description  of  an  icon. 

library 

ptolemy.moml. Library  Attribute 

Associates  an  actor  library  with  a  model. 

libraryMarker 

ptolemy.kemel.util.  Attribute 

Marks  its  container  as  a  library  vs.  a  composite  entity. 

location 

ptolemy.moml. Location 

Records  the  location  of  a  visual  rendition  of  an  object. 

nonStrictMarker 

ptolemy.kemel.util.  Attribute 

Marks  its  container  as  a  non-strict  entity. 

_parser 

ptolemy.moml. ParserAttribute 

Records  the  MoML  parser  used. 

_url 

ptolemy.moml.URLAttribute 

Identifies  the  URL  for  the  model  definition. 

vergilLocation 

ptolemy.actor.gui. LocationAttribute 

Location  of  the  vergil  window. 

vergilSize 

ptolemy.  actor,  gui .  S  ize  Attribute 

Size  of  the  graph  pane  in  the  vergil  window. 

1.3.5  List  Classes 

Figures  1.2  and  1.3  show  two  list  classes  that  are  used  extensively  in  Ptolemy  II,  NamedList  and 
CrossRefList.  These  pre-date  the  extensive  list  classes  in  the  java.util  package,  and  could  probably  be 
replaced  with  those  today.  NamedList  implements  an  ordered  list  of  objects  with  the  Nameable  inter- 
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face.  It  is  unlike  a  hash  table  in  that  it  maintains  an  ordering  of  the  entries  that  is  independent  of  their 
names.  It  is  unlike  a  vector  or  a  linked  list  in  that  it  supports  accesses  by  name.  It  is  used,  for  example, 
to  maintain  a  list  of  attributes  and  to  maintain  the  list  of  ports  contained  by  an  entity. 

The  class  CrossRefList  (figure  1.4)  is  a  bit  more  interesting.  It  mediates  bidirectional  links 
between  objects  that  contain  CrossRefLists,  in  this  case,  ports  and  relations.  It  provides  a  simple  and 
efficient  mechanism  for  constructing  a  web  of  objects,  where  each  object  maintains  a  list  of  the  objects 
it  is  linked  to.  That  list  is  an  instance  of  CrossRefList.  The  class  ensures  consistency.  That  is,  if  one 
object  in  the  web  is  linked  to  another,  then  the  other  is  linked  back  to  the  one.  CrossRefList  also  han¬ 
dles  efficient  modification  of  the  cross  references.  In  particular,  if  a  link  is  removed  from  the  list  main¬ 
tained  by  one  object,  the  back  reference  in  the  remote  object  also  has  to  be  deleted.  This  is  done  in 
0(1)  time.  A  more  brute  force  solution  would  require  searching  the  remote  list  for  the  back  reference, 
increasing  the  time  required  and  making  it  proportional  to  the  number  of  links  maintained  by  each 
object. 

1.4  Clustered  Graphs  and  Hierarchy 

The  classes  shown  in  figure  1.2  provide  only  partial  support  for  hierarchy,  through  the  concept  of  a 
container.  Subclasses,  shown  in  figure  1.6,  extend  these  with  more  complete  support  for  hierarchy. 
ComponentEntity,  ComponentPort,  and  ComponentRelation  are  used  whenever  a  clustered  graph  is 
used.  All  ports  of  a  ComponentEntity  are  required  to  be  instances  of  ComponentPort.  CompositeEntity 
extends  ComponentEntity  with  the  capability  of  containing  ComponentEntity  and  ComponentRelation 
objects.  Thus,  it  contains  a  subgraph.  The  association  between  ComponentEntity  and  CompositeEntity 
is  the  classic  Composite  design  pattern  [44]. 

1.4.1  Abstraction 

Composite  entities  are  non-atomic  (isAtomic()  returns  false).  They  can  contain  a  graph  (entities 
and  relations).  By  default,  a  CompositeEntity  is  transparent  (isOpaque()  returns  false).  Conceptually, 
this  means  that  its  contents  are  visible  from  the  outside.  The  hierarchy  can  be  ignored  (flattened)  by 
algorithms  operating  on  the  topology.  Some  subclasses  of  CompositeEntity  are  opaque  (see  the  Actor 
Package  chapter  for  examples).  This  forces  algorithms  to  respect  the  hierarchy,  effectively  hiding  the 
contents  of  a  composite  and  making  it  appear  indistinguishable  from  atomic  entities. 

A  ComponentPort  contained  by  a  CompositeEntity  has  inside  as  well  as  outside  links.  It  maintains 
two  lists  of  links,  those  to  relations  inside  and  those  to  relations  outside.  Such  a  port  serves  to  expose 
ports  in  the  contained  entities  as  ports  of  the  composite.  This  is  the  converse  of  the  “hiding”  operator 
often  found  in  process  algebras  [108].  In  Ptolemy,  ports  within  an  entity  are  hidden  by  default,  and 
must  be  explicitly  exposed  to  be  visible  (linkable)  from  outside  the  entity1.  The  composite  entity  with 
ports  thus  provides  an  abstraction  of  the  contents  of  the  composite. 

A  port  of  a  composite  entity  may  be  opaque  or  transparent.  It  is  defined  to  be  opaque  if  its  con¬ 
tainer  is  opaque.  Conceptually,  if  it  is  opaque,  then  its  inside  links  are  not  visible  from  the  outside,  and 
the  outside  links  are  not  visible  from  the  inside.  If  it  is  opaque,  it  appears  from  the  outside  to  be  indis¬ 
tinguishable  from  a  port  of  an  atomic  entity. 

The  transparent  port  mechanism  is  illustrated  by  the  example  in  figure  1.7  .  Some  of  the  ports  in 
figure  1.7  are  filled  in  white  rather  than  black.  These  ports  are  said  to  be  transparent.  Transparent  ports 


1.  Unless  level-crossing  links  are  allowed,  which  is  discouraged. 
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(P3  and  P4)  are  linked  to  relations  (R1  and  R2)  below  their  container  (El)  in  the  hierarchy.  They  may 
also  be  linked  to  relations  at  the  same  level  (R3  and  R4). 

ComponentPort,  ComponentRelation,  and  CompositeEntity  have  a  set  of  methods  with  the  prefix 
“deep,”  as  shown  in  figure  1.6.  These  methods  flatten  the  hierarchy  by  traversing  it.  Thus,  for  example, 
the  ports  that  are  “deeply”  connected  to  port  PI  in  figure  1.7  are  P2,  P5,  and  P6.  No  transparent  port  is 
included,  so  note  that  P3  and  P4  are  not  included. 

Deep  traversals  of  a  graph  follow  a  simple  rule.  If  a  transparent  port  is  encountered  from  inside, 
then  the  traversal  continues  with  its  outside  links.  If  it  is  encountered  from  outside,  then  the  traversal 
continues  with  its  inside  links.  Thus,  for  example,  the  ports  deeply  connected  to  P5  are  PI  and  P2. 
Note  that  P6  is  not  included.  Similarly,  the  deepEntityList()  method  of  CompositeEntity  looks  inside 
transparent  entities,  but  not  inside  opaque  entities. 

Since  deep  traversals  are  more  expensive  than  just  checking  adjacent  objects,  both  ComponentPort 
and  ComponentRelation  cache  them.  To  determine  the  validity  of  the  cached  list,  the  version  of  the 
workspace  is  used.  As  shown  in  figure  6.3,  the  Workspace  class  includes  a  getVersion()  and  incrVer- 
sion()  method.  All  methods  of  objects  within  a  workspace  that  modify  the  topology  in  any  way  are 
expected  to  increment  the  version  count  of  the  workspace.  That  way,  when  a  deep  access  is  performed 
by  a  ComponentPort,  it  can  locally  store  the  resulting  list  and  the  current  version  of  the  workspace. 
The  next  time  the  deep  access  is  requested,  it  checks  the  version  of  the  workspace.  If  it  is  still  the  same, 
then  it  returns  the  locally  cached  list.  Otherwise,  it  reconstructs  it. 

For  ComponentPort  to  support  both  inside  links  and  outside  links,  it  has  to  override  the  linkQ  and 
unlinkQ  methods.  Given  a  relation  as  an  argument,  these  methods  can  determine  whether  a  link  is  an 
inside  link  or  an  outside  link  by  checking  the  container  of  the  relation.  If  that  container  is  also  the  con¬ 
tainer  of  the  port,  then  the  link  is  an  inside  link. 


FIGURE  1.7.  Transparent  ports  (P3  and  P4)  are  linked  to  relations  (R1  and  R2)  below  their  container  (El) 
in  the  hierarchy.  They  may  also  be  linked  to  relations  at  the  same  level  (R3  and  R4). 


2.  In  that  figure,  every  object  has  been  given  a  unique  name.  This  is  not  necessary  since  names  only  need  to  be 
unique  within  a  container.  In  this  case,  we  could  refer  to  P5  by  its  foil  name  .E0.E4.P5  (the  leading  period  indi¬ 
cates  that  this  name  is  absolute).  However,  using  unique  names  makes  our  explanations  more  readable. 
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ComponentPort 


insideLinks  :  CrossRefList 


+ComponentEntity() 

+ComponentEntity(workspace  :  Workspace) 
+ComponentEntity(container :  CompositeEntity,  name  :  String)| 
+isAtomic()  :  boolean 
+isOpaque()  :  boolean 
+setContainer(container :  CompositeEntity) 
#_checkContainer(container :  Prototype) 

0..n  containee 


+ComponentPort() 

+ComponentPort(workspace  :  Workspace) 

+ComponentPort(container :  ComponentEntity,  name  :  String) 

+deepConnectedPortList() :  List 

+deeplnsidePortList() :  List 

+insertlnsideLink(index  :  int,  relation  :  Relation) 

+insidePortList() :  List 

+insideRelationList() :  List 

+insideRelations() :  Enumeration 

+isDeeplyConnected(port :  ComponentPort)  :  boolean 

+islnsideLinked(relation  :  Relation) :  boolean 

+isOpaque()  :  boolean 

+liberalLink(relation  :  ComponentRelation) 

+numlnsideLinks() :  int 
+unlinkAlllnside() 

+unlinklnside(index  :  int) 

+unlinklnside(relation  :  Relation) 

|#_checkLiberalLink(relation  :  Relation) 
#_deepConnectedPortList(path  :  LinkedList) 


#_containedEntities  :  NamedList 
-  containedRelations  :  NamedList 


+CompositeEntity() 

+CompositeEntity(workspace  :  Workspace) 

+CompositeEntity(container :  CompositeEntity,  name  :  String) 

+allAtomicEntityList()  :  List 
+allowLevelCrossingConnect(boole  :  boolean) 

+classDefinitionList() :  List 

+connect(p1  :  ComponentPort,  p2  :  ComponentPort)  :  ComponentRelation 

+connect(p1  :  ComponentPort,  p2  :  ComponentPort,  name  :  String) :  ComponentRelation 

+deepEntityList() :  List 

+entityList() :  List 

+entityList(filter :  Class) :  List 

+exportLinks(indentation  :  int,  filter :  Collection) :  String 
+getEntity(name  :  String)  :  ComponentEntity 
+getRelation(name  :  String)  :  ComponentRelation 
+newRelation(name  :  String) :  ComponentRelation 
+numberOfClassDefinitions()  :  int 
+numberOfEntities() :  int 
+numberOfRelations()  :  int 
+relationList() :  List 
+removeAIIEntities() 

+removeAIIRelations() 

#_addEntity(entity  :  ComponentEntity) 

#_addRelation(relation  :  ComponentRelation) 

#_removeEntity(entity  :  ComponentEntity) 

#_removeRelation(relation  :  ComponentRelation) 


ComponentRelation 


_container :  CompositeEntity 


+ComponentRelation() 

+ComponentRelation(workspace  :  Workspace) 
+ComponentRelation(container :  CompositeEntity,  name  :  String) 
+deeplinkedPortList()  :  List 
+setContainer(container :  CompositeEntity) 
|#_checkContainer(container :  CompositeEntity) 


0..1 


0..n  containee 


FIGURE  1.6.  Key  classes  supporting  clustered  graphs. 
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1.4.2  Relation  Groups 

Relations  mediate  connections  between  ports.  For  flexibility,  particularly  with  visual  syntaxes,  the 
Ptolemy  II  abstract  syntax  permits  any  number  of  relations  to  be  involved  in  any  one  connection.  Fig¬ 
ure  1.8  illustrates  this.  Relations  may  be  linked  to  other  relations.  Any  two  relations  that  are  linked  are 
said  to  be  members  of  the  same  relation  group.  Specifically,  a  relation  group  is  a  maximal  set  of  linked 
relations.  Semantically,  a  relation  group  has  the  same  meaning  as  a  single  relation.  Thus,  the  two  dia¬ 
grams  in  figure  1.8  have  the  same  meaning.  The  API  of  the  Relation  class,  as  shown  in  figure  1.2,  sup¬ 
port  linking  and  unlinking  relations,  and  also  provides  a  method  to  obtain  a  list  of  all  the  relations  in  a 
relation  group. 

In  a  relation  group,  there  is  no  significance  to  the  order  in  which  relations  are  linked,  unlike  the 
order  in  which  ports  are  linked  to  relations.  Also,  unlike  links  between  relations  and  ports,  there  is  no 
significance  to  multiple  links  between  the  same  relations.  Any  two  relations  are  either  linked  or  not 
linked. 

1.4.3  Level-Crossing  Connections 

For  a  few  applications,  such  as  Statecharts  [52],  level-crossing  links  and  connections  are  needed. 
The  example  shown  in  figure  1.9  has  three  level-crossing  connections  that  are  slightly  different  from 
one  another.  The  links  in  these  connections  are  created  using  the  liberalLink()  method  of  Component- 
Port.  The  link()  method  prohibits  such  links,  throwing  an  exception  if  they  are  attempted  (most  appli¬ 
cations  will  prohibit  level-crossing  connections  by  using  only  the  linkQ  method). 

An  alternative  that  may  be  more  convenient  for  a  user  interface  is  to  use  the  connect()  methods  of 
CompositeEntity  rather  than  the  link()  or  liberalLinkQ  method  of  ComponentPort.  To  allow  level¬ 
crossing  links  using  connect(),  first  call  allowLevelCrossingConnect()  with  a  true  argument. 

The  simplest  level-crossing  connection  in  figure  1.9  is  at  the  bottom,  connecting  P2  to  P7  via  the 
relation  R5.  The  relation  is  contained  by  El ,  but  the  connection  would  be  essentially  identical  if  it  were 
contained  by  any  other  entity.  Thus,  the  notion  of  composite  entities  containing  relations  is  somewhat 
weaker  when  level-crossing  connections  are  allowed. 

The  other  two  level-crossing  connections  in  figure  1.9  are  mediated  by  transparent  ports.  This  sort 
of  hybrid  could  come  about  in  heterogeneous  representations,  where  level-crossing  connections  are 
permitted  in  some  parts  but  not  in  others.  It  is  important,  therefore,  for  the  classes  to  support  such 


FIGURE  1.8.  A  relation  group  is  maximal  set  of  linked  relations.  At  the  left,  Rl,  R2,  and  R3  form  a  rela¬ 
tion  group.  A  relation  group  is  semantically  identical  to  a  single  relation,  so  the  two  diagrams  above  have 
the  same  meaning. 
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hybrids. 

To  support  such  hybrids,  we  have  to  modify  slightly  the  algorithm  by  which  a  port  recognizes  an 
inside  link.  Given  a  relation  and  a  port,  the  link  is  an  inside  link  if  the  relation  is  contained  by  an  entity 
that  is  either  the  same  as  or  is  deeply  contained  (i.e.  directly  or  indirectly  contained)  by  the  entity  that 
contains  the  port.  The  deepContains()  method  of  NamedObj  supports  this  test. 

1.4.4  Tunneling  Entities 

The  transparent  port  mechanism  we  have  described  supports  connections  like  that  between  PI  and 
P5  in  figure  1.10.  That  connection  passes  through  the  entity  E2.  The  relation  R2  is  linked  to  the  inside 


FIGURE  1.9.  An  example  with  level-crossing  transitions. 


FIGURE  1.10.  A  tunneling  entity  contains  a  relation  with  inside  links  to  more  than  one  port. 
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of  each  of  P2  and  P4,  in  addition  to  its  link  to  the  outside  of  P3.  Thus,  the  ports  deeply  connected  to  PI 
are  P3  and  P5,  and  those  deeply  connected  to  P3  are  PI  and  P5,  and  those  deeply  connected  to  P5  are 
PI  and  P3. 

A  tunneling  entity  is  one  that  contains  a  relation  with  links  to  the  inside  of  more  than  one  port.  It 
may  of  course  also  contain  more  standard  links,  but  the  term  “tunneling”  suggests  that  at  least  some 
deep  graph  traversals  will  see  right  through  it. 

Support  for  tunneling  entities  is  a  major  increment  in  capability  over  the  previous  Ptolemy  kernel 
[23]  (Ptolemy  Classic).  That  infrastructure  required  an  entity  (which  was  called  a  star)  to  intervene  in 
any  connection  through  a  composite  entity  (which  was  called  a  galaxy ).  Two  significant  limitations 
resulted.  The  first  was  that  compositionality  was  compromised.  A  connection  could  not  be  subsumed 
into  a  composite  entity  without  fundamentally  changing  the  structure  of  the  application  (by  introduc¬ 
ing  a  new  intervening  entity).  The  second  was  that  implementation  of  higher-order  functions  that 
mutated  the  graph  [87]  was  made  much  more  complicated.  These  higher-order  functions  had  to  be 
careful  to  avoid  mutations  that  created  tunneling. 

1.4.5  Cloning 

The  kernel  classes  are  all  capable  of  being  cloned,  with  some  restrictions.  Cloning  means  that  an 
identical  but  entirely  independent  object  is  created.  Thus,  if  the  object  being  cloned  contains  other 
objects,  then  those  objects  are  also  cloned.  If  those  objects  are  linked,  then  the  links  are  replicated  in 
the  new  objects.  The  clone()  method  in  NamedObj  provides  the  interface  for  doing  this.  Each  subclass 
provides  an  implementation. 

There  is  a  key  restriction  to  cloning.  Because  they  break  modularity,  level-crossing  links  prevent 
cloning.  With  level-crossing  links,  a  link  does  not  clearly  belong  to  any  particular  entity.  An  attempt  to 
clone  a  composite  that  contains  level-crossing  links  will  trigger  an  exception. 

1.4.6  An  Elaborate  Example 

An  elaborate  example  of  a  clustered  graph  is  shown  in  figure  1.11.  This  example  includes 
instances  of  all  the  capabilities  we  have  discussed.  The  top-level  entity  is  named  “EO.”  All  other  enti¬ 
ties  in  this  example  have  containers.  A  Java  class  that  implements  this  example  is  shown  in  figure  1.12. 
A  script  in  the  Tel  language  [123]  that  constructs  the  same  graph  is  shown  in  figure  1.13.  This  script 
uses  Tel  Blend,  an  interface  between  Tel  and  Java  that  is  distributed  by  Scriptics.  Such  scripts  are  used 
extensively  in  the  Ptolemy  II  regression  test  suite. 

The  order  in  which  links  are  constructed  matters,  in  the  sense  that  methods  that  return  lists  of 
objects  preserve  this  order.  The  order  implemented  in  both  figures  1.12  and  1.13  is  top-to-bottom  and 
left-to-right  in  figure  1.11.  A  graphical  syntax,  however,  does  not  generally  have  a  particularly  conve¬ 
nient  way  to  completely  control  this  order. 

The  results  of  various  method  accesses  on  the  graph  are  shown  in  figure  1.14.  This  table  can  be 
studied  to  better  understand  the  precise  meaning  of  each  of  the  methods. 

1.5  Opaque  Composite  Entities 

One  of  the  major  tenets  of  the  Ptolemy  project  is  that  of  modeling  heterogeneous  systems  through 
the  use  of  hierarchical  heterogeneity.  Information-hiding  is  a  central  part  of  this.  In  particular,  transpar¬ 
ent  ports  and  entities  compromise  information  hiding  by  exposing  the  internal  topology  of  an  entity.  In 
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some  circumstances,  this  is  inappropriate,  for  example  when  the  entity  internally  operates  under  a  dif¬ 
ferent  model  of  computation  from  its  environment.  The  entity  should  be  opaque  in  this  case. 

An  entity  can  be  opaque  and  composite  at  the  same  time.  Ports  are  defined  to  be  opaque  if  the 
entity  containing  them  is  opaque  (isOpaque()  returns  true),  so  deep  traversals  of  the  topology  do  not 
cross  these  ports,  even  though  the  ports  support  inside  and  outside  links.  The  actor  package  makes 
extensive  use  of  such  entities  to  support  mixed  modeling.  That  use  is  described  in  the  Actor  Package 
chapter.  In  the  previous  generation  system,  Ptolemy  Classic,  composite  opaque  entities  were  called 
wormholes. 

1.6  Concurrency 

Concurrency  is  an  expected  property  in  many  models.  Network  topologies  may  represent  the 
structure  of  computations  which  themselves  may  be  concurrent,  and  a  user  interface  may  be  interacting 
with  the  topologies  while  they  execute  their  computation.  Moreover,  Ptolemy  II  objects  may  interact 
with  other  objects  concurrently  over  the  network  via  RMI,  datagrams,  TCP/IP,  or  CORBA. 

Both  computations  within  an  entity  and  the  user  interface  are  capable  of  modifying  the  topology. 


FIGURE  1.11.  An  example  of  a  clustered  graph. 
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public  class  ExampleSystem  { 

private 

CompositeEntity  eO,  e3,  e4,  e7,  elO; 

private 

ComponentEntity  el,  e2,  e5,  e6,  e8,  e9; 

private 

ComponentPort  pO,  pi,  p2,  p3,  p4,  p5,  p6,  p7,  p8. 

P9, 

plO,  pll, 

pl2,  pl3,  p4; 

private 

ComponentRelation  rl,  r2,  r3,  r4,  r5,  r6,  r7,  r8. 

r9. 

rlO,  rll, 

rl2; 

public  ExampleSystem ()  throws  IllegalActionException,  NameDuplicationException  { 

eO  = 

new  CompositeEntity () ; 

eO  .  setName ("EO") ; 

e3  = 

new  CompositeEntity (eO,  "E3"); 

e4  = 

new  CompositeEntity (e3,  "E4"); 

el  = 

new  CompositeEntity (eO,  "E7"); 

elO 

=  new  CompositeEntity (eO,  "ElO"); 

el  = 

new  ComponentEntity (e4,  "El"); 

e2  = 

new  ComponentEntity (e4,  "E2"); 

e5  = 

new  ComponentEntity (e3,  "E5"); 

e6  = 

new  ComponentEntity (e3,  "E6"); 

e8  = 

new  ComponentEntity (e7,  "E8"); 

e9  = 

new  ComponentEntity (elO,  "E9"); 

pO  = 

(ComponentPort)  e4 .newPort ("PO") ; 

pi  = 

(ComponentPort)  el .newPort ("PI") ; 

p2  = 

(ComponentPort)  e2 .newPort ("P2") ; 

p3  = 

(ComponentPort)  e2 .newPort ("P3") ; 

p4  = 

(ComponentPort)  e4 .newPort ("P4") ; 

p5  = 

(ComponentPort)  e5 .newPort ("P5") ; 

p6  = 

(ComponentPort)  e5 .newPort ("P6") ; 

P7  = 

(ComponentPort)  e3 .newPort ("P7") ; 

P8  = 

(ComponentPort)  e7 .newPort ("P8") ; 

p9  = 

(ComponentPort)  e8 .newPort ("P9") ; 

plO 

=  (ComponentPort)  e8 .newPort ("PlO") ; 

pll 

=  (ComponentPort)  e7 .newPort ("Pll") ; 

p!2 

=  (ComponentPort)  elO. newPort ("P12") ; 

pl3 

=  (ComponentPort)  elO. newPort ( " PI 3 " ) ; 

pl4 

=  (ComponentPort)  e9 .newPort ("P14") ; 

rl  = 

e4 . connect (pi,  pO,  "Rl"); 

r2  = 

e4 . connect (pi,  p4,  "R2" ); 

p3 . link (r2) ; 

r3  = 

e4 . connect (pi,  p2,  "R3"); 

r4  = 

e3. connect (p4,  p7,  "R4"); 

r5  = 

e3. connect (p4,  p5,  "R5"); 

e3 . allowLevelCrossingConnect (true) ; 

r6  = 

e3. connect (p3,  p6,  "R6"); 

r7  = 

eO  .  connect (p7,  pl3,  "Rl") ; 

r8  = 

el  .connect (p9,  p8,  "R8"); 

r9  = 

e7  .connect (pi 0 ,  pll,  "R9"); 

rlO 

=  eO .connect (p8,  pl2,  "RIO"); 

rll 

=  elO .connect (pl2,  pl3,  "Rll"); 

rl2 

=  elO . connect (pi 4 ,  pl3,  "R12"); 

pll. 

} 

} 

link ( r 7 ) ; 

FIGURE  1.12.  The  same  topology  as  in  figure  1.11  implemented  as  a  Java  class. 
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Thus,  extra  care  is  needed  to  make  sure  that  the  topology  remains  consistent  in  the  face  of  simulta¬ 
neous  modifications  (we  defined  consistency  in  section  1.2.2). 

Concurrency  could  easily  corrupt  a  topology  if  a  modification  to  a  symmetric  pair  of  references  is 
interrupted  by  another  thread  that  also  tries  to  modify  the  pair.  Inconsistency  could  result  if,  for  exam¬ 
ple,  one  thread  sets  the  reference  to  the  container  of  an  object  while  another  thread  adds  the  same 
object  to  a  different  container’s  list  of  contained  objects.  Ptolemy  II  prevents  such  inconsistencies  from 
occurring.  Such  enforced  consistency  is  called  thread  safety. 


#  Create  composite  entities 

set 

eO  [java::new  pt . kernel . CompositeEntity 

EO] 

set 

e3  [java: mew  pt . kernel . CompositeEntity 

$e0 

E3] 

set 

e4  [java: mew  pt . kernel . CompositeEntity 

$e3 

E4  ] 

set 

e7  [java: mew  pt . kernel . CompositeEntity 

$e0 

E7] 

set 

elO  [java: mew  pt . kernel . CompositeEntity  $e0  E10] 

#  Create  component  entities. 

set 

el  [java: mew  pt . kernel . ComponentEntity 

$e4 

El] 

set 

e2  [java: mew  pt . kernel . ComponentEntity 

$e4 

E2] 

set 

e5  [java: mew  pt . kernel . ComponentEntity 

$e3 

E5] 

set 

e6  [java: mew  pt . kernel . ComponentEntity 

$e3 

E6] 

set 

e8  [java: mew  pt . kernel . ComponentEntity 

$e7 

E8] 

set 

e9  [java: mew  pt . kernel . ComponentEntity 

$e!0  E9] 

#  Create  ports. 

set 

pO  [$e4  newPort  PO] 

set 

pi  [$el  newPort  PI] 

set 

p2  [$e2  newPort  P2] 

set 

p3  [$e2  newPort  P3] 

set 

p4  [$e4  newPort  P4] 

set 

p5  [$e5  newPort  P5] 

set 

p6  [$e6  newPort  P6] 

set 

p7  [$e3  newPort  P7] 

set 

p8  [$e7  newPort  P8] 

set 

p9  [$e8  newPort  P9] 

set 

plO  [$e8  newPort  P10] 

set 

pll  [$e7  newPort  PI 1 ] 

set 

pl2  [$elO  newPort  P12] 

set 

pl3  [$elO  newPort  P13] 

set 

pl4  [$e9  newPort  P14] 

#  Create  links 

set 

rl  [$e4  connect  $pl  $p0  Rl] 

set 

r2  [$e4  connect  $pl  $p4  R2] 

$p3 

link  $r2 

set 

r3  [$e4  connect  $pl  $p2  R3] 

set 

r4  [$e3  connect  $p4  $p7  R4] 

set 

r5  [$e3  connect  $p4  $p5  R5] 

$e3 

allowLevelCrossingConnect  true 

set 

r6  [$e3  connect  $p3  $p6  R6] 

set 

r7  [$e0  connect  $p7  $pl3  R7] 

set 

r8  [$e7  connect  $p9  $p8  R8] 

set 

r9  [$e7  connect  $plO  $pll  R9] 

set 

rlO  [$e0  connect  $p8  $pl2  RIO] 

set 

rll  [$elO  connect  $pl2  $pl3  Rll] 

set 

r!2  [$e!0  connect  $p!4  $p!3  R12] 

$pll  link  $r7 

FIGURE  1.13.  The  same  topology  as  in  figure  1.11  described  by  the  Tel  commands  to  create  it. 


Heterogeneous  Concurrent  Modeling  and  Design 


17 


The  Kernel 


1.6.1  Limitations  of  Monitors 

Java  threads  provide  a  low-level  mechanism  called  a  monitor  for  controlling  concurrent  access  to 
data  structures.  A  monitor  locks  an  object  preventing  other  threads  from  accessing  the  object  (a  design 
pattern  called  mutual  exclusion).  Unfortunately,  the  mechanism  is  fairly  tricky  to  use  correctly.  It  is 
non-trivial  to  avoid  deadlock  and  race  conditions.  One  of  the  major  objectives  of  Ptolemy  II  is  provide 
higher-level  concurrency  models  that  can  be  used  with  confidence  by  non  experts. 

Monitors  are  invoked  in  Java  via  the  “synchronized”  keyword.  This  keyword  annotates  a  body  of 
code  or  a  method,  as  shown  in  figure  1.15.  It  indicates  that  an  exclusive  lock  should  be  obtained  on  a 
specific  object  before  executing  the  body  of  code.  If  the  keyword  annotates  a  method,  as  in  figure 
1. 15(a),  then  the  method’s  object  is  locked  (an  instance  of  class  A  in  the  figure).  The  keyword  can  also 
be  associated  with  an  arbitrary  body  of  code  and  can  acquire  a  lock  on  an  arbitrary  object.  In  figure 
1.15(b),  the  code  body  represented  by  brackets  {...}  can  be  executed  only  after  a  lock  has  been 
acquired  on  object  obj. 

Modifications  to  a  topology  that  run  the  risk  of  corrupting  the  consistency  of  the  topology  involve 
more  than  one  object.  Java  does  not  directly  provide  any  mechanism  for  simultaneously  acquiring  a 
lock  on  multiple  objects.  Acquiring  the  locks  sequentially  is  not  good  enough  because  it  introduces 
deadlock  potential,  i.e.,  one  thread  could  acquire  the  lock  on  the  first  object  block  trying  to  acquire  a 
lock  on  the  second,  while  a  second  thread  acquires  a  lock  on  the  second  object  and  blocks  trying  to 
acquire  a  lock  on  the  first.  Both  methods  block  permanently,  and  the  application  is  deadlocked.  Neither 
thread  can  proceed. 


Table  l.lrMethods  of  ComponentRelation 


Method  Name 

R1 

R2 

R3 

R4 

R5 

R6 

R7 

R8 

R9 

RIO 

Rll 

R12 

getLinkedPorts 

PI 

PI 

PI 

P4 

P4 

P3 

P7 

P9 

P10 

P8 

P12 

P14 

PO 

P4 

P2 

P7 

P5 

P6 

P13 

P8 

Pll 

P12 

P13 

P13 

P3 

Pll 

deepGetLinkedPorts 

PI 

PI 

PI 

PI 

PI 

P3 

PI 

P9 

P10 

P9 

P9 

P14 

P9 

P2 

P3 

P3 

P6 

P3 

PI 

PI 

PI 

PI 

PI 

P14 

P9 

P5 

P9 

P3 

P3 

P3 

P3 

P3 

P10 

P14 

P14 

P10 

P9 

P10 

P10 

P10 

P5 

P10 

P10 

P14 

P3 

Table  1.2:Methods  of  ComponentPort 


Method  Name 

PO 

PI 

P2 

P3 

P4 

P5 

P6 

P7 

P8 

P9 

P10 

Pll 

P12 

P13 

P14 

getConnectedPorts 

PO 

PI 

PI 

P7 

P4 

P3 

P13 

P12 

P8 

Pll 

P7 

P8 

P7 

P13 

P4 

P4 

P5 

Pll 

P13 

Pll 

P3 

P6 

P2 

deepGetConnectedPorts 

P9 

PI 

PI 

P9 

PI 

P3 

P9 

PI 

PI 

PI 

PI 

P9 

PI 

PI 

P14 

P9 

P14 

P3 

P14 

P3 

P3 

P3 

P3 

P3 

P3 

P10 

P14 

P10 

P10 

P10 

P10 

P9 

P9 

P10 

P10 

P5 

P10 

P5 

P14 

P14 

P3 

P5 

P2 

P6 

FIGURE  1.14.  Key  methods  applied  to  figure  1.11. 
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One  possible  solution  is  to  ensure  that  locks  are  always  acquired  in  the  same  order  [75].  For  exam¬ 
ple,  we  could  use  the  containment  hierarchy  and  always  acquire  locks  top-down  in  the  hierarchy.  Sup¬ 
pose  for  example  that  a  body  of  code  involves  two  objects  a  and  b,  where  a  contains  b  (directly  or 
indirectly).  In  this  case,  “involved”  means  that  it  either  modifies  members  of  the  objects  or  depends  on 
their  values.  Then  this  body  of  code  would  be  surrounded  by: 

synchronized (a)  { 

synchronized  (b)  { 

} 

} 


If  all  code  that  locks  a  and  b  respects  this  same  order,  then  deadlock  cannot  occur.  However,  if  the 
code  involves  two  objects  where  one  does  not  contain  the  other,  then  it  is  not  obvious  what  ordering  to 
use  in  acquiring  the  locks.  Worse,  a  change  might  be  initiated  that  reverses  the  containment  hierarchy 
while  another  thread  is  in  the  process  of  acquiring  locks  on  it.  A  lock  must  be  acquired  to  read  the  con¬ 
tainment  structure  before  the  containment  structure  can  be  used  to  acquire  a  lock!  Some  policy  could 
certainly  be  defined,  but  the  resulting  code  would  be  difficult  to  guarantee.  Moreover,  testing  for  dead¬ 
lock  conditions  is  notoriously  difficult,  so  we  implement  a  more  conservative,  and  much  simpler  strat¬ 
egy- 


public  class  A  { 

public  synchronized  void  foot)  { 


(a) 


public  class  B  { 

public  void  foo()  { 
synchronized (obj )  { 


(b) 


public  class  C  extends  NamedObj  { 
public  void  foo()  { 

synchronized (workspace () )  { 


try  { 

workspace () . getReadAccess () ; 
//  ...  code  that  reads 
}  finally  { 

workspace ( ) . doneReading ( ) ; 

} 


(d) 


try  { 

workspace!)  . getWriteAccess  ()  ; 
//  ...  code  that  writes 
}  finally  { 

workspace ( ) . doneWriting ( ) ; 

} 


(e) 


(c) 

FIGURE  1.15.  Using  monitors  for  thread  safety.  The  method  used  in  Ptolemy  II  is  in  (d)  and  (e). 
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1.6.2  Read  and  Write  Access  Permissions  for  Workspace 

One  way  to  guarantee  thread  safety  without  introducing  the  risk  of  deadlock  is  to  give  every  object 
an  immutable  association  with  another  object,  which  we  call  its  workspace.  Immutable  means  that  the 
association  is  set  up  when  the  object  is  constructed,  and  then  cannot  be  modified.  When  a  change 
involves  multiple  objects,  those  objects  must  be  associated  with  the  same  workspace.  We  can  then 
acquire  a  lock  on  the  workspace  before  making  any  changes  or  reading  any  state,  preventing  other 
threads  from  making  changes  at  the  same  time. 

Ptolemy  II  uses  monitors  on  instances  of  the  class  Workspace.  As  shown  in  figure  1.3,  every 
instance  of  NamedObj  (or  derived  classes)  is  associated  with  a  single  instance  of  Workspace.  Each 
body  of  code  that  alters  or  depends  on  the  topology  must  acquire  a  lock  on  its  workspace.  Moreover, 
the  workspace  associated  with  an  object  is  immutable.  It  is  set  in  the  constructor  and  never  modified. 
This  is  enforced  by  a  very  simple  mechanism:  a  reference  to  the  workspace  is  stored  in  a  private  vari¬ 
able  of  the  base  class  NamedObj,  as  shown  in  figure  1.3,  and  no  methods  are  provided  to  modify  it. 
Moreover,  in  instances  of  these  kernel  classes,  a  container  and  its  containees  must  share  the  same 
workspace  (derived  classes  may  be  more  liberal  in  certain  circumstances).  This  “managed  ownership” 
[75]  is  our  central  strategy  in  thread  safety. 

As  shown  in  figure  1.15(c),  a  conservative  approach  would  be  to  acquire  a  monitor  on  the  work¬ 
space  for  each  body  of  code  that  reads  or  modified  objects  in  the  workspace.  However,  this  approach  is 
too  conservative.  Instead,  Ptolemy  II  allows  any  number  of  readers  to  simultaneously  access  a  work¬ 
space.  Only  one  writer  can  access  the  workspace,  however,  and  only  if  no  readers  are  concurrently 
accessing  the  workspace. 

The  code  for  readers  and  writers  is  shown  in  figure  1.15(d)  and  (e).  In  (d),  a  reader  first  calls  the 
getReadAccess()  method  of  the  Workspace  class.  That  method  does  not  return  until  it  is  safe  to  read 
data  anywhere  in  the  workspace.  It  is  safe  if  there  is  no  other  thread  concurrently  holding  (or  request¬ 
ing)  a  write  lock  on  the  workspace  (the  thread  calling  getReadAccess()  may  safely  hold  both  a  read 
and  a  write  lock).  When  the  user  is  finished  reading  the  workspace  data,  it  must  call  doneReading(). 
Failure  to  do  so  will  result  in  no  writer  ever  again  gaining  write  access  to  the  workspace.  Because  it  is 
so  important  to  call  this  method,  it  is  enclosed  in  the  finally  clause  of  a  try  statement.  That  clause  is 
executed  even  if  an  exception  occurs  in  the  body  of  the  try  statement. 

The  code  for  writers  is  shown  in  figure  1.15(e).  The  writer  first  calls  the  getWriteAccess()  method 
of  the  Workspace  class.  That  method  does  not  return  until  it  is  safe  to  write  into  the  workspace.  It  is 
safe  if  no  other  thread  has  read  or  write  permission  on  the  workspace.  The  calling  thread,  of  course, 
may  safely  have  both  read  and  write  permission  at  the  same  time.  Once  again,  it  is  essential  that  done- 
Writing()  be  called  after  writing  is  complete. 

This  solution,  while  not  as  conservative  as  the  single  monitor  of  figure  1.15(c),  is  still  conservative 
in  that  mutual  exclusion  is  applied  even  on  write  actions  that  are  independent  of  one  another  if  they 
share  the  same  workspace.  This  effectively  serializes  some  modifications  that  might  otherwise  occur  in 
parallel.  However,  there  is  no  constraint  in  Ptolemy  II  on  the  number  of  workspaces  used,  so  sub¬ 
classes  of  these  kernel  classes  could  judiciously  use  additional  workspaces  to  increase  the  parallelism. 
But  they  must  do  so  carefully  to  avoid  deadlock.  Moreover,  most  of  the  methods  in  the  kernel  refuse  to 
operate  on  multiple  objects  that  are  not  in  the  same  workspace,  throwing  an  exception  on  any  attempt 
to  do  so.  Thus,  derived  classes  that  are  more  liberal  will  have  to  implement  their  own  mechanisms  sup¬ 
porting  interaction  across  workspaces. 

There  is  one  significant  subtlety  regarding  read  and  write  permissions  on  the  workspace.  In  a  mul¬ 
tithreaded  application,  normally,  when  a  thread  suspends  (for  example  by  calling  wait()),  if  that  thread 
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holds  read  permission  on  the  workspace,  that  permission  is  not  relinquished  during  the  time  the  thread 
is  suspended.  If  another  thread  requires  write  permission  to  perform  whatever  action  the  first  thread  is 
waiting  for,  then  deadlock  will  ensue.  That  thread  cannot  get  write  access  until  the  first  thread  releases 
its  read  permission,  and  the  first  thread  cannot  continue  until  the  second  thread  gets  write  access. 

The  way  to  avoid  this  situation  is  to  use  the  wait()  method  of  Workspace,  passing  as  an  argument 
the  object  on  which  you  wish  to  wait  (see  Workspace  methods  in  figure  1.3).  That  method  first  relin¬ 
quishes  all  read  permissions  before  calling  wait  on  the  target  object.  When  wait()  returns,  notice  that  it 
is  possible  that  the  topology  has  changed,  so  callers  should  be  sure  to  re-read  any  topology-dependent 
information.  In  general,  this  technique  should  be  used  whenever  a  thread  suspends  while  it  holds  read 
permissions. 

1.7  Mutations 

Often  it  is  necessary  to  carefully  constrain  when  changes  can  be  made  in  a  topology.  For  example, 
an  application  that  uses  the  actor  package  to  execute  a  model  defined  by  a  topology  may  require  the 
topology  to  remain  fixed  during  segments  of  the  execution.  The  util  subpackage  of  the  kernel  package 
provides  support  for  carefully  controlled  mutations  that  can  occur  during  the  execution  of  a  model.  The 
relevant  classes  and  interfaces  are  shown  in  figure  1.16.  Also  shown  in  the  figure  is  the  most  useful 
mutation  class,  MoMLChangeRequest,  which  uses  MoML  to  specify  the  mutation.  That  class  is  in  the 
moml  package. 

The  usage  pattern  involves  a  source  that  wishes  to  have  a  mutation  performed,  such  as  an  actor 
(see  the  Actor  Package  chapter)  or  a  user  interface  component.  The  originator  creates  an  instance  of 
the  class  ChangeRequest  and  enqueues  that  request  by  calling  the  requestChange()  of  any  object  in  the 
Ptolemy  II  hierarchy.  That  object  typically  delegates  the  request  to  the  top-level  of  the  hierarchy,  which 
in  turn  delegates  to  the  manager.  When  it  is  safe,  the  manager  executes  the  change  by  calling  execute() 
on  each  enqueued  ChangeRequest.  In  addition,  it  informs  any  registered  change  listeners  of  the  muta¬ 
tions  so  that  they  can  react  accordingly.  Their  changeExecuted()  method  is  called  if  the  change  suc¬ 
ceeds,  and  their  changeFailedQ  method  is  called  if  the  change  fails.  The  list  of  listeners  is  maintained 
by  the  manager,  so  when  a  listener  is  added  to  or  removed  from  any  object  in  the  hierarchy,  that  request 
is  delegated  to  the  manager. 

1.7.1  Change  Requests 

A  manager  processes  a  change  request  by  calling  its  execute()  method.  That  method  then  calls  the 
protected  _execute()  method,  which  actually  performs  the  change.  If  the  _execute()  method  completes 
successfully,  then  the  ChangeRequest  object  notifies  listeners  of  success.  If  the  _execute()  method 
throws  an  exception,  then  the  ChangeRequest  object  notifies  listeners  of  failure. 

The  ChangeRequest  class  is  abstract.  Its  _execute()  method  is  undefined.  In  a  typical  use,  an  origi¬ 
nator  will  define  an  anonymous  inner  class,  like  this: 

CompositeEntity  container  =  ...  ; 

ChangeRequest  change  =  new  ChangeRequest (originator,  "description")  { 
protected  void  execute ()  throws  Exception  { 

. . .  perform  change  here  . .  . 

} 

1  ; 

container . requestChange (change) ; 
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Object 


«lnterface» 

Changeable 


+addChangeListener(listener :  ChangeListener) 
+executeChangeRequests() 
+isDeferringChangeRequests()  :  boolean 
+removeChangeListener(listener :  ChangeListener) 
+requestChange(change  :  ChangeRequest) 
+setDeferringChangeRequests(isDeferring  :  boolean) 


request  change 
specifies  the  list  of  listeners 


NamedObj 


|#_changeListeners  :  List: 


delegates  change  request  to  container 


-_description  :  String 
-_errorReported  :  boolean 
-exception  :  Exception 
■Jisteners  :  List 
-_pending  :  boolean 
■_persistent :  boolean 
-_source  :  Object 


executes  the  change 


notifies  of  completion 


+ChangeRequest(source  :  Object,  description  :  String) 
+addChangeListener(listener :  ChangeListener) 
+execute() 

+getDescription() :  String 
+getLocality() :  NamedObj 
+getSource() :  Object 
+isErrorReported()  :  boolean 
+isPersistent() :  boolean 

+removeChangeListener(listener :  ChangeListener) 
+setDescription(description  :  String) 
+setErrorReported(reported  :  boolean) 
+setListeners(listeners  :  List) 

+setPersistent(persistent :  boolean) 
+waitForCompletion() 

#_execute() 


«lnterface» 

ChangeListener 


+changeExecuted(change :  ChangeRequest) 
+changeFai!ed(change :  ChangeRequest,  error :  Exception )\ 


■_output :  PrintStream 


moml  package 


+StreamChangeListener() 
+StreamChangeListener(out :  OutputStream)! 


MoMLChangeRequest 


-_base  :  URL 
-_context :  NamedObj 
-_mergeWithPreviousUndo  :  boolean 
-_parser :  MoMLParser 
-_propagating  :  boolean 
-_reportToHandler :  boolean 
-_undoable  :  boolean 

+MoMLChangeRequest(originator :  Object,  request :  String) 
+MoMLChangeRequest(originator :  Object,  context :  NamedObj,  request :  String) 
+MoMLChangeRequest(originator :  Object,  context :  NamedObj,  request :  String,  base  :  URL) 
+qetDeferredToParent(obiect :  NamedObj) :  NamedObj 
+setUndoable(undoable  :  boolean) 

+setMergeWithPreviousUndo(merge  :  boolean) 

+setReportErrorsToHandler( report :  boolean) 


FIGURE  1.16.  Classes  and  interfaces  that  support  controlled  topology  mutations.  A  source  requests  topology 
changes  and  a  manager  performs  them  at  a  safe  time. 
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By  convention,  the  change  request  is  usually  posted  with  the  container  that  will  be  affected  by  the 
change.  The  body  of  the  _execute()  method  can  create  entities,  relations,  ports,  links,  etc.  For  example, 
the  code  in  the  _execute()  method  to  create  and  link  a  new  entity  might  look  like  this: 

Entity  newEntity  =  new  MyEntityClass (originator,  "NewEntity" ) ; 
relation . link (newEntity. port) ; 

When  _execute()  is  called,  the  entity  named  newEntity  will  be  created,  added  to  originator  (which  is 
assumed  to  be  an  instance  of  CompositeEntity  here)  and  linked  to  relation. 

A  key  concrete  class  extending  ChangeRequest  is  implemented  in  the  moml  package,  as  shown  in 
figure  1.16.  The  MoMLChangeRequest  class  supports  specification  of  a  change  in  MoML.  See  the 
MoML  chapter  for  details  about  how  to  write  MoML  specifications  for  changes.  The  context  argument 
to  the  second  constructor  typically  gives  a  composite  entity  within  which  the  commands  should  be 
interpreted.  Thus,  the  same  change  request  as  above  could  be  accomplished  as  follows: 

CompositeEntity  container  =  ...  ; 

String  moml  =  "<group>" 

+  "<entity  name=\"\"  class=\"MyEntityClass\"/>" 

+  "<link  port=\ "portname\ "  relation=\ "relationname\ " />" 

+  "</group>"; 

ChangeRequest  change  = 

new  MoMLChangeRequest (originator,  container,  moml); 

container . requestChange (change)  ; 


1.7.2  NamedObj  and  Listeners 

The  NamedObj  class  provides  addChangeListener()  and  removeChangeListener()  methods,  so  that 
interested  objects  can  register  to  be  notified  when  topology  changes  occur.  In  addition,  it  provides  a 
method  that  originators  can  use  to  queue  requests,  requestChange(). 

A  change  listener  is  any  object  that  implements  the  ChangeListener  interface,  and  will  typically 
include  user  interfaces  and  visualization  components.  The  instance  of  ChangeRequest  is  passed  to  the 
listener.  Typically  the  listener  will  call  getOriginator()  to  determine  whether  it  is  being  notified  of  a 
change  that  it  requested.  This  might  be  used  for  example  to  determine  whether  a  requested  change  suc¬ 
ceeds  or  fails. 

The  ChangeRequest  class  also  provides  a  waitForCompletion()  method.  This  method  will  not 
return  until  the  change  request  completes.  If  the  request  fails  with  an  exception,  then  waitForComple- 
tion()  will  throw  that  exception.  Note  that  this  method  can  be  quite  dangerous  to  use.  It  will  not  return 
until  the  change  request  is  processed.  If  for  some  reason  change  requests  are  not  being  processed  (due 
for  a  example  to  a  bug  in  user  code  in  some  actor),  then  this  method  will  never  return.  If  you  make  the 
mistake  of  calling  this  method  from  within  the  event  thread  in  Java,  then  if  it  never  returns,  the  entire 
user  interface  will  freeze,  no  longer  responding  to  inputs  from  the  keyboard  or  mouse,  nor  repainting 
the  screen.  The  user  will  have  no  choice  but  to  kill  the  program,  possibly  losing  his  or  her  work. 
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1.8  Actor-Oriented  Classes 

The  kernel  and  kernel.util  packages  provide  support  for  a  significant  innovation  that  was  intro¬ 
duced  with  Ptolemy  II  version  4.0,  namely  actor-oriented  classes,  subclasses,  and  inner  classes,  with 
inheritance.  In  this  mechanism,  an  entity  can  serve  as  either  a  class  definition  or  as  an  instance  of  a 
class.  It  can  also  be  a  subclass  of  another  entity  that  is  a  class  definition.  When  a  change  is  made  to  a 
class  definition,  then  the  change  propagates  to  all  subclasses  and  instances.  The  mechanism  is 
described  in  [79]. 

The  key  principle  that  is  followed  in  Ptolemy  II  is  called  the  derivation  invariant.  The  derivation 
invariant  is  an  assertion  that  if  any  class  definition  contains  an  object  (an  entity,  port,  relation, 
attribute),  then  all  subclasses  and  instances  contain  a  derived  object,  which  has  the  same  name  and 
Java  class.  The  derived  object  is  said  to  be  implied  by  and  derived  from  the  first  object.  The  first  object 
is  called  the  prototype  of  the  derived  object.  Thus,  the  structure  of  a  subclass  or  instance  includes  at 
least  the  objects  that  are  included  in  the  class  definition. 

A  class  definition  is  said  to  be  the  parent  of  a  subclass  or  an  instance.  The  subclass  or  instance  is 
said  to  be  the  child. 

Inner  classes  are  supported  in  the  following  sense:  a  class  definition  x  can  contain  an  entity  y  that  is 
itself  a  class  definition.  Consider  the  example  shown  in  figure  1.17.  If  x  has  an  instance  x' ,  then  x' 
contains  a  class  definition  y' ,  by  the  derivation  invariant.  If  x  contains  an  instance  z  of  y ,  then  x'  con¬ 
tains  an  instance  z'  of  y' .  Notice  that  z'  is  an  instance  of  y' ,  but  is  also  implied  by  z  in  x,  by  the  deri¬ 
vation  invariant.  Thus,  if  a  change  is  made  to  any  of  y,  z  or  y' ,  (e.g.,  an  attribute  is  added)  a 
corresponding  change  must  be  made  to  z'  so  that  the  derivation  invariant  is  satisfied.  This  is  a  disci¬ 
plined  form  of  multiple  inheritance. 

As  mentioned  before,  some  attributes  implement  the  Settable  interface,  shown  in  figure  1.5.  Such 
attributes  have  a  value  (a  representation  of  which  is  returned  by  the  getExpression()  method  of  the  Set- 
table  interface).  If  an  attribute  is  implied  by  another  attribute,  then  by  default  it  has  the  same  value  as 
the  other  object.  However,  that  value  can  be  overridden.  Since  there  is  multiple  inheritance,  there  may 
be  multiple  paths  by  which  a  value  propagates  from  an  attribute  to  another  that  is  derived  from  it.  The 
key  principle  in  Ptolemy  II  is  that  local  value  changes  take  precedence  over  less  local  value  changes. 

Consider  the  example  given  above.  Suppose  that  y ,  z ,  / ,  and  z'  all  have  values.  Suppose  further 
than  y  overrides  that  value.  Then  unless  z'  also  overrides  the  value,  then  z'  will  inherit  its  value  from 
y .  Suppose  that  after  this  override  is  established,  the  value  of  y  is  changed.  That  new  value  will  be 
inherited  by  z ,  but  not  by  y' ,  and  z' ,  which  override  it.  The  reason  is  that  the  derivation  path  from  y  to 
y ,  and  z'  is  higher  in  the  hierarchy  (and  hence  less  local)  than  the  path  from  y'  to  z' . 

We  will  now  outline  how  this  mechanism  is  implemented.  The  two  key  interfaces  are  Derivable 
and  Instantiable,  shown  in  figure  1.3.  NamedObj  implements  Derivable,  which  means  that  any  Name- 
dObj  can  be  derived  from  another  NamedObj.  Only  InstantiableNamedObj,  shown  in  figure  1.2, 
implements  Instantiable.  Since  Entity  is  a  subclass  of  InstantiableNamedObj,  an  instance  of  Entity  or 
any  subclass  can  be  either  a  class  definition  or  an  instance. 


x< - x  ’ 


FIGURE  1.17.  Example  showing  containment  relations  as  vertical  lines  and  parent-child  relations  as  hori¬ 
zontal  arrows. 
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The  Derivable  interface  has  a  getDerivedLevel()  method  that  returns  an  indicator  of  locality.  It  has 
a  getDerivedList()  method  that  returns  a  list  of  derived  objects,  with  more  locally  derived  objects 
appearing  earlier  in  the  list  than  less  locally  derived  objects.  In  the  example  above,  the  derived  list  for 
that  y  is  {z ,  y' ,  z' },  in  that  order.  It  has  a  getPrototypeList()  method  that  returns  the  list  of  prototypes 
(if  there  are  any)  for  a  specified  object.  This  list  includes  only  direct  prototypes  (those  not  traversing 
more  than  one  parent-child  relation).  So  for  z' ,  the  prototype  list  is  {z ,  y'  }  but  not  z . 

The  derivation  invariant  is  realized  by  the  propagateExistence()  method  of  the  Derivable  interface. 
The  inheritance  of  values  is  realized  by  the  propagate Value()  method. 

The  other  key  interface.  Instantiate,  supports  the  parent-child  relation,  and  provides  an  instanti- 
ate()  method  that  is  used  to  create  either  subclasses  or  instances.  Instantiation  is  accomplished  by  clon¬ 
ing,  although  there  are  significant  subtleties  in  the  implementation.  For  instance,  when  x  in  the  above 
example  is  instantiated  to  create  x' ,  within  the  instance,  it  is  important  that  the  parent  of  z'  is  y'  not  y . 
The  instantiate()  method  ensures  this. 

1.9  Exceptions 

Ptolemy  II  includes  a  set  of  exception  classes  that  provide  a  uniform  mechanism  for  reporting 
errors  that  takes  advantage  of  the  identification  of  named  objects  by  full  name.  These  exception  are 
summarized  in  the  class  diagram  in  figure  1.18. 

1.9.1  Base  Class 

KernelException.  Not  used  directly.  Provides  common  functionality  for  the  kernel  exceptions.  In  par¬ 
ticular,  it  provides  methods  that  take  zero,  one,  or  two  Nameable  objects  an  optional  cause  (a  Throw- 
able)  plus  an  optional  detail  message  (a  String).  The  arguments  provided  are  arranged  in  a  default 
organization  that  is  overridden  in  derived  classes. 

The  cause  argument  to  the  constructor  is  a  Throwable  that  caused  the  exception.  The  cause  argu¬ 
ment  is  used  when  code  throws  an  exception  and  we  want  to  rethrow  the  exception  but  print  the  stack- 
trace  where  the  first  exception  occurred.  This  is  called  exception  chaining. 

JDK1.4  supports  exception  chaining.  We  are  implementing  a  version  of  exception  chaining  here 
ourselves  so  that  we  can  use  JVMs  earlier  than  JDK1 .4. 

In  this  implementation,  we  have  the  following  differences  from  the  JDK1.4  exception  chaining 
implementation: 

•  In  this  implementation,  the  detail  message  includes  the  detail  message  from  the  cause  argument. 

•  In  this  implementation,  we  implement  a  protected  _setCause()  method,  but  not  the  public  init- 
Cause()  method  that  JDK1.4  has. 

1.9.2  Less  Severe  Exceptions 

These  exceptions  generally  indicate  that  an  operation  failed  to  complete.  These  can  result  in  a 
topology  that  is  not  what  the  caller  expects,  since  the  caller’s  modifications  to  the  topology  did  not  suc¬ 
ceed.  However,  they  should  never  result  in  an  inconsistent  or  contradictory  topology. 

Illegal ActionException.  Thrown  on  an  attempt  to  perform  an  action  that  is  disallowed.  For  example, 
the  action  would  result  in  an  inconsistent  or  contradictory  data  structure  if  it  were  allowed  to  complete. 
Example:  an  attempt  to  set  the  container  of  an  object  to  be  another  object  that  cannot  contain  it  because 
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Exception 

jRuntimeException 

Kernel  RuntimeException 

<3 - 1 

-  cause  :  Throwable 

-_message  :  String 

- 

+KernelRuntimeException() 

+KernelRuntimeException(objects  :  Collection,  cause  :  Throwable,  detail  :  String) 
+KernelRuntimeException(o1  :  Nameable,  o2  :  Nameable,  cause  :  Throwable,  detail  :  String) 
+KernelRuntimeException(object :  Nameable,  detail  :  String) 

+KernelRuntimeException(detail :  String) 

+KernelRuntimeException(cause  :  Throwable,  detail :  String) 

+getCause() :  Throwable 
+getMessage() :  String 

KernelException 

+printStackT  race() 

+printStackTrace(printStream  :  printStream) 

+printStackTrace(printWriter :  PrintWriter) 

-_cause  :  Throwable 
-_message  :  String 

#_setCause(cause  :  Throwable) 

#_setMessage(message  :  String) 

+KernelException() 

+KernelException(o1  :  Nameable,  o2  :  Nameable,  detail :  String) 

+KernelException(o1  :  Nameable,  o2  :  Nameable,  cause  :  Throwable,  detail :  String) 
qenerateMessaqefol  :  Nameable,  o2  :  Nameable,  cause  :  Throwable,  detail  :  String) : 


String 


qenerateMessaqefprefix  :  String,  cause  :  Throwable.  detail  :  String) :  String 
+getCause() :  Throwable 
+qetFullName(obiect :  Nameable) :  String 
+getMessage() :  String 
+qetName(obiect :  Nameable) :  String 
+printStackT  race() 

+printStackTrace(printStream  :  PrintStream) 

+printStackTrace(printWriter :  PrintWriter) 

+stackTraceToStrinq(throwable  :  Throwable) : 

#_setCause(cause  :  Throwable) 

#_setMessage(message  :  String) 


:  String 


InternalErrorException 


+lnternalErrorException(o  :  Nameable,  cause  :  Throwable,  detail :  String)| 
|+lnternalErrorException(detail  :  String) 

-HnternalErrorException(cause  :  Throwable) 


InvalidStateException 


message  :  String 


+lnvalidStateException(objects  :  Collection,  detail :  String) 

+lnvalidStateException(objects  :  Collection,  cause  :  Throwable,  detail :  String) 
+lnvalidStateException(o1  :  Nameable,  o2  :  Nameable,  detail  :  String) 
+lnvalidStateException(o1  :  Nameable,  o2  :  Nameable,  cause  :  Throwable,  detail :  String)| 
|+lnvalidStateException(object :  Nameable,  detail :  String) 

+lnvalidStateException(object :  Nameable,  cause  :  Throwable,  detail  :  String) 
+lnvalidStateException(detail :  String) 


NoSuchltemException 


+NoSuchltemException(object :  Nameable,  detail :  String) 
+NoSuchltemException(object :  Nameable,  cause  :  Throwable,  detail :  String) 
+NoSuchltemException(detail :  String) 


FIGURE  1.18.  Summary  of  exceptions  defined  in  the  kemel.util  package.  These  are  used  primarily  through 
constructor  calls.  The  form  of  the  constructors  is  shown  in  the  text.  Exception  and  RuntimeException  are 
Java  exceptions. 
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it  is  of  the  wrong  class. 

NameDuplicationException.  Thrown  on  an  attempt  to  add  a  named  object  to  a  collection  that  requires 
unique  names,  and  finding  that  there  already  is  an  object  by  that  name  in  the  collection. 

NoSuchltemException.  Thrown  on  access  to  an  item  that  doesn't  exist.  Example:  an  attempt  to  remove 
a  port  by  name  and  no  such  port  exists. 

1.9.3  More  Severe  Exceptions 

The  following  exceptions  should  never  trigger.  If  they  trigger,  it  indicates  a  serious  inconsistency 
in  the  topology  and/or  a  bug  in  the  code.  At  the  very  least,  the  topology  being  operated  on  should  be 
abandoned  and  reconstructed  from  scratch.  They  are  runtime  exceptions,  so  they  do  not  need  to  be 
explicitly  declared  to  be  thrown. 

KernelRuntimeException.  Base  class  for  runtime  exceptions.  This  class  extends  the  basic  Java  Runt- 
imeException  with  a  constructor  that  can  take  a  Nameable  as  an  argument.  This  exception  supports  all 
the  constructor  forms  of  KemelException,  but  is  implemented  as  a  RuntimeException  so  that  it  does 
not  have  to  be  declared..  In  particular,  it  provides  methods  that  take  zero,  one,  or  two  Nameable  objects 
an  optional  cause  (a  Throwable)  plus  an  optional  detail  message  (a  String).  The  arguments  provided 
are  arranged  in  a  default  organization  that  is  overridden  in  derived  classes.  The  cause  argument  is  used 
to  implement  a  form  of  exception  chaining. 

InvalidStateException.  Some  object  or  set  of  objects  has  a  state  that  in  theory  is  not  permitted.  Exam¬ 
ple:  a  NamedObj  has  a  null  name.  Or  a  topology  has  inconsistent  or  contradictory  information  in  it, 
e.g.,  an  entity  contains  a  port  that  has  a  different  entity  as  its  container.  Our  design  should  make  it 
impossible  for  this  exception  to  ever  occur,  so  occurrence  is  a  bug.  This  exception  is  derived  from  the 
Java  RuntimeException. 

InternalError Exception.  An  unexpected  error  other  than  an  inconsistent  state  has  been  encountered. 
Our  design  should  make  it  impossible  for  this  exception  to  ever  occur,  so  occurrence  is  a  bug.  This 
exception  is  derived  from  the  Java  RuntimeException. 
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2.1  Concurrent  Computation 

In  the  kernel  package,  entities  have  no  semantics.  They  are  syntactic  placeholders.  In  many  of  the 
uses  of  Ptolemy  II,  entities  are  executable.  The  actor  package  provides  basic  support  for  executable 
entities.  It  makes  a  minimal  commitment  to  the  semantics  of  these  entities  by  avoiding  specifying  the 
order  in  which  actors  execute  (or  even  whether  they  execute  sequentially  or  concurrently),  and  by 
avoiding  specifying  the  communication  mechanism  between  actors.  These  properties  are  defined  in  the 
domains. 

In  most  uses,  these  executable  entities  conceptually  (if  not  actually)  execute  concurrently.  The  goal 
of  the  actor  package  is  to  provide  a  clean  infrastructure  for  such  concurrent  execution  that  is  neutral 
about  the  model  of  computation.  It  is  intended  to  support  dataflow,  discrete-event,  synchronous-reac¬ 
tive,  continuous-time,  communicating  sequential  processes,  and  process  networks  models  of  computa¬ 
tion,  at  least.  The  detailed  model  of  computation  is  then  implemented  in  a  set  of  derived  classes  called 
a  domain.  Each  domain  is  a  separate  package. 

Ptolemy  II  is  an  object-oriented  application  framework.  Actors  [1]  extend  the  concept  of  objects  to 
concurrent  computation.  Actors  encapsulate  a  thread  of  control  and  have  interfaces  for  interacting  with 
other  actors.  They  provide  a  framework  for  “open  distributed  object-oriented  systems.”  An  actor  can 
create  other  actors,  send  messages,  and  modify  its  own  local  state. 
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Inspired  by  this  model,  we  group  a  certain  set  of  classes  that  support  computation  within  entities  in 
the  actor  package.  Our  use  of  the  term  “actors,”  however,  is  somewhat  broader,  in  that  it  does  not 
require  an  entity  to  be  associated  with  a  single  thread  of  control,  nor  does  it  require  the  execution  of 
threads  associated  with  entities  to  be  fair.  Some  subclasses,  in  other  packages,  impose  such  require¬ 
ments,  as  we  will  see,  but  not  all. 

Agha’s  actors  [1]  can  only  send  messages  to  acquaintances  —  actors  whose  addresses  it  was  given 
at  creation  time,  or  whose  addresses  it  has  received  in  a  message,  or  actors  it  has  created.  Our  equiva¬ 
lent  constraint  is  that  an  actor  can  only  send  a  message  to  an  actor  if  it  has  (or  can  obtain)  a  reference  to 
a  receiver  belonging  to  an  input  port  of  that  actor.  The  usual  mechanism  for  obtaining  a  reference  to  a 
receiver  uses  the  topology,  probing  for  a  port  that  it  is  connected  to.  Our  relations,  therefore,  provide 
explicit  management  of  acquaintance  associations.  Derived  classes  may  provide  additional  implicit 
mechanisms.  We  define  actor  more  loosely  to  refer  to  an  entity  that  processes  data  that  it  receives 
through  its  ports,  or  that  creates  and  sends  data  to  other  entities  through  its  ports. 

The  actor  package  provides  templates  for  two  key  support  functions.  These  templates  support  mes¬ 
sage  passing  and  the  execution  sequence  (flow  of  control).  They  are  templates  in  that  no  mechanism  is 
actually  provided  for  message  passing  or  flow  of  control,  but  rather  base  classes  are  defined  so  that 
domains  only  need  to  override  a  few  methods,  and  so  that  domains  can  interoperate. 

2.2  Message  Passing 

The  actor  package  provides  templates  for  executable  entities  called  actors  that  communicate  with 
one  another  via  message  passing.  Messages  are  encapsulated  in  tokens  (see  the  Data  Package  chapter). 
Messages  are  sent  and  received  via  ports.  IOPort  is  the  key  class  supporting  message  transport,  and  is 
shown  in  figure  2.2.  An  IOPort  can  only  be  connected  to  other  IOPort  instances,  and  only  via  IORela- 
tions.  The  IORelation  class  is  also  shown  in  figure  2.2.  TypedlOPort  and  TypedlORelation  are  sub¬ 
classes  that  manage  type  resolution.  These  subclasses  are  used  much  more  often,  in  order  to  benefit 
from  the  type  system.  This  is  described  in  detail  in  the  Type  System  chapter. 

An  instance  of  IOPort  can  be  an  input,  an  output,  or  both.  An  input  port  (one  that  is  capable  of 
receiving  messages)  contains  one  or  more  instances  of  objects  that  implement  the  Receiver  interface. 
Each  of  these  receivers  is  capable  of  receiving  messages  from  a  distinct  channel. 

The  type  of  receiver  used  depends  on  the  communication  protocol,  which  depends  on  the  model  of 
computation.  The  actor  package  includes  two  receivers,  Mailbox  and  QueueReceiver.  These  are 
generic  enough  to  be  useful  in  several  domains.  The  QueueReceiver  class  contains  a  FIFOQueue,  the 
capacity  of  which  can  be  controlled.  It  also  provides  a  mechanism  for  tracking  the  history  of  tokens 
that  are  received  by  the  receiver.  The  Mailbox  class  implements  a  FIFO  (first  in,  first  out)  queue  with 
capacity  equal  to  one. 

2.2.1  Data  Transport 

Data  transport  is  depicted  in  figure  2.1.  The  originating  actor  El  has  an  output  port  PI,  indicated  in 
the  figure  with  an  arrow  in  the  direction  of  token  flow.  The  destination  actor  E2  has  an  input  port  P2, 
indicated  in  the  figure  with  another  arrow.  El  calls  the  send()  method  of  PI  to  send  a  token  t  to  a 
remote  actor.  The  port  obtains  a  reference  to  a  remote  receiver  (via  the  IORelation)  and  calls  the  put() 
method  of  the  receiver,  passing  it  the  token.  The  destination  actor  retrieves  the  token  by  calling  the 
get()  method  of  its  input  port,  which  in  turn  calls  the  get()  method  of  the  designated  receiver. 

Domains  typically  provide  specialized  receivers.  These  receivers  override  get()  and  put()  to  imple- 
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ment  the  communication  protocol  pertinent  to  that  domain.  A  domain  that  uses  asynchronous  message 
passing,  for  example,  can  usually  use  the  QueueReceiver  shown  in  figure  2.2.  A  domain  that  uses  syn¬ 
chronous  message  passing  (rendezvous)  has  to  provide  a  new  receiver  class. 

In  figure  2.1  there  is  only  a  single  channel,  indexed  0.  The  “0”  argument  of  the  sendQ  and  get() 
methods  refer  to  this  channel.  A  port  can  support  more  than  one  channel,  however,  as  shown  in  figure 
2.3.  This  can  be  represented  by  linking  more  than  one  relation  to  the  port,  or  by  linking  a  relation  that 
has  a  width  greater  than  one.  A  port  that  supports  this  is  called  a  multiport.  The  channels  are  indexed 
0,  . ..,  N  -  1 ,  where  N  is  the  number  of  channels.  An  actor  distinguishes  between  channels  using  this 
index  in  its  sendQ  and  get()  methods.  By  default,  an  IOPort  is  not  a  multiport,  and  thus  supports  only 
one  channel  (or  zero,  if  it  is  left  unconnected).  It  is  converted  into  a  multiport  by  calling  its  setMulti- 
port()  method  with  a  true  argument.  After  conversion,  it  can  support  any  number  of  channels. 

Multiports  are  typically  used  by  actors  that  communicate  via  an  indeterminate  number  of  channels. 
For  example,  a  “distributor”  or  “demultiplexor”  actor  might  divide  an  input  stream  into  a  number  of 
output  streams,  where  the  number  of  output  streams  depends  on  the  connections  made  to  the  actor.  A 
stream  is  a  sequence  of  tokens  sent  over  a  channel. 

An  IORelation,  by  default,  represents  a  single  channel.  By  calling  its  setWidth()  method,  however, 
it  can  be  converted  to  a  bus.  A  multiport  may  use  a  bus  instead  of  multiple  relations  to  distribute  its 
data,  as  shown  in  figure  2.4.  The  width  of  a  relation  is  the  number  of  channels  supported  by  the  rela¬ 
tion.  If  the  relation  is  not  a  bus,  then  its  width  is  one. 

The  width  of  a  port  is  the  sum  of  the  widths  of  the  relations  linked  to  it.  In  figure  2.4,  both  the 
sending  and  receiving  ports  are  multiports  with  width  two.  This  is  indicated  by  the  “2”  adjacent  to  each 
port.  Note  that  the  width  of  a  port  could  be  zero,  if  there  are  no  relations  linked  to  a  port  (such  a  port  is 
said  to  be  disconnected).  Thus,  a  port  may  have  width  zero,  even  though  a  relation  cannot.  By  conven¬ 
tion,  in  Ptolemy  II,  if  a  token  is  sent  from  such  a  port,  the  token  goes  nowhere.  Similarly,  if  a  token  is 


FIGURE  2.1.  Message  passing  is  mediated  by  the  IOPort  class.  Its  send()  method  obtains  a  reference  to  a 
remote  receiver,  and  calls  the  put()  method  of  the  receiver,  passing  it  the  token  t.  The  destination  actor 
retrieves  the  token  by  calling  the  get()  method  of  its  input  port. 


FIGURE  2.3.  A  port  can  support  more  than  one  channel,  permitting  an  entity  to  send  distinct  data  to  distinct 
destinations  via  the  same  port.  This  feature  is  typically  used  when  the  number  of  destinations  varies  in  dif¬ 
ferent  instances  of  the  source  actor. 
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NoRoomException 


+NoRoomException(message  :  String) 
+NoRoomException(obj  :  Nameable,  message  :  String)! 


NoTokenException 


+CONFIGURATION  :  int 
+RECEIVERS  :  int 
+REMOTERECEIVERS  :  int 
-Jslnput :  boolean 
-JsMultiport :  boolean 
•JsOutput :  boolean 
■  localReceiversTable  :  Hashtable 


IOPort() 

|+IOPort(container :  ComponentEntity,  name  :  String) 

IOPort(container :  ComponentEntity,  name  :  String,  islnput :  boolean,  isOutput :  boolean)| 
+IOPort(w :  Workspace) 

+broadcast(token  :  Token) 

+broadcast(tokenArray  :  Token[],  vectorLength  :  int) 

+broadcastAbsent() 

+createReceivers() 

+deepConnectedlnPortList() :  List 
+deepConnectedOutPortList() :  List 
+deepGetReceivers() :  Receiver[][] 

+get(channellndex  :  int) :  Token 
+get(channellndex  :  int,  vectorLength  :  int) :  Token 
+getCurrentTime(channellndex  :  int) :  double 
+getlnsideReceivers() :  Receiver[][] 

+getReceivers() :  Receiver[][] 

+getReceivers(relation  :  lORelation) :  Receiver[][] 

+getReceivers(relation  :  lORelation,  occurrance  :  int) :  Receiver[][] 

+getRemoteReceivers() :  Receiver[][] 

+getRemoteReceivers(relation  :  lORelation) :  Receiver[][] 

+getWidth() :  int 

+hasRoom(channellndex  :  int) :  boolean 
+hasToken(channellndex  :  int) :  boolean 
+hasToken(channellndex  :  int,  tokens  :  int) :  boolean 
+insideSinkPortList() :  List 
+islnput() :  boolean 
isKnown() :  boolean 
isKnown(channellndex  :  int) :  boolean 
isMultiport() :  boolean 
isOutput() :  boolean 

+send(channellndex  :  int,  token  :  Token) 

+send(channellndex  :  int,  tokenArray  :  Tokenf],  vectorLength  :  int) 
+sendAbsent(channellndex :  int) 

+setlnput(islnput :  boolean) 

+setMultiport(isMultiport :  boolean) 

+setOutput(isOutput :  boolean) 

+sinkPortList() :  List 
+sourcePortList() :  List 
+transferlnputs() :  boolean 
+transferOutputs() :  boolean 
#_getlnsideWidth(except :  lORelation) :  int 
#_newlnsideReceiver() :  Receiver 
#_newReceiver() :  Receiver 


+NoTokenException(message  :  String) 
_+NoTokenException(obj  :  Nameable,  message  :  String)! 


«lnterface» 

Receiver 


+get() :  Token 

+getArray(numberOfT okens  :  int)  :  Token/] 

+getContainer() :  lOPort 
+hasRoom()  :  boolean 
+hasRoom(numberOfT okens  :  int)  :  boolean 
+hasToken() :  boolean 
+hasToken(numberOfT okens  :  int) :  boolean 
+isKnown() :  boolean 
+put(t :  Token) 

+putArray(tokenArray :  Token/],  numberOfT okens  :  int)  :  void\ 
+setAbsent() 

+setContainer(port :  lOPort) 


Abstrac  t  Receiver 


+AbstractReceiver() 
+AbstractReceiver(container :  lOPort)! 


|#_queue  :  FIFOQueue 
container :  lOPort 


1+CONFIGURATION  :  int 
width  :  int 


+IORelation() 

+IORelation(workspace  :  Workspace) 
+IORelation(container :  CompositeActor,  name  :  String)| 
+deepReceivers(except :  lOPort) :  Receiver  QQ 
+getWidth() :  int 
+isWidthFixed() :  boolean 
+linkedDestinationPortList() :  List 
+linkedDestinationPortList(except :  lOPort) :  List 
+HnkedSourcePortList() :  List 
+linkedSourcePortList(except :  lOPort) :  List 
+setWidth(width  :  int) 


_container :  lOPort 
token  :  Token 


+Mailbox() 

+Mailbox(container :  lOPort)! 


QueueReceiver 


+INFINITE  CAPACITY  :  int 


+QueueReceiver() 
+QueueReceiver(container :  IOPort)| 
+elementList() :  List 
+get(offset :  int) :  Token 
+getCapacity() :  int 
+getHistoryCapacity() :  int 
+historyElementList() :  List 
+historySize() :  int 
+reset() 

+setCapacity(capacity :  int) 
+setHistoryCapacity(capacity  :  int) 
+size() :  int 


FIFOQueue 


FIGURE  2.2.  Port  and  receiver  classes  for  message  passing  under  various  communication  protocols. 
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sent  via  a  relation  that  is  not  linked  to  any  input  ports,  then  the  token  goes  nowhere.  Such  a  relation  is 
said  to  be  dangling. 

A  given  channel  may  reach  multiple  ports,  as  shown  in  figure  2.5.  This  is  represented  by  a  relation 
that  is  linked  to  multiple  input  ports.  In  the  default  implementation,  in  class  IOPort,  a  reference  to  the 
token  is  sent  to  all  destinations.  Note  that  tokens  are  assumed  to  be  immutable,  so  the  recipients  cannot 
modify  the  value.  This  is  important  because  in  most  domains,  it  is  not  obvious  in  what  order  the  recip¬ 
ients  will  see  the  token. 

The  send()  method  takes  a  channel  number  argument.  If  the  channel  does  not  exist,  the  send() 
method  silently  returns  without  sending  the  token  anywhere.  This  makes  it  easier  for  model  builders, 
since  they  can  simply  leave  ports  unconnected  if  they  are  not  interested  in  the  output  data. 

IOPort  provides  a  broadcast()  method  for  convenience.  This  method  sends  a  specified  token  to  all 
receivers  linked  to  the  port,  regardless  of  the  width  of  the  port.  If  the  width  is  zero,  of  course,  the  token 
will  not  be  sent  anywhere. 

2.2.2  Example 

An  elaborate  example  showing  all  of  the  above  features  is  shown  in  figure  2.6.  In  that  example,  we 
assume  that  links  are  constructed  in  top-to-bottom  order.  The  arrows  in  the  ports  indicate  the  direction 
of  the  flow  of  tokens,  and  thus  specify  whether  the  port  is  an  input,  an  output,  or  both.  Multiports  are 
indicated  by  adjacent  numbers  larger  than  one. 

The  top  relation  is  a  bus  with  width  two,  and  the  rest  are  not  busses.  The  width  of  port  PI  is  four. 
Its  first  two  outputs  (channels  zero  and  one)  go  to  P4  and  to  the  first  two  inputs  of  P5.  The  third  output 
of  PI  goes  nowhere.  The  fourth  becomes  the  third  input  of  P5,  the  first  input  of  P6,  and  the  only  input 
of  P8,  which  is  both  an  input  and  an  output  port.  Ports  P2  and  P8  send  their  outputs  to  the  same  set  of 


receiver.put(tO) 


A  N.  receiver.  put(t1 ) 

send(0,t0)--^A^ - ^  j 

f^-get(O),  get(1)^ 
K  po  F? 

A-  *  2 1 

l  send(l.tl)— -y/  K1  1 

■ J  rz 

token  to,  t1> 

FIGURE  2.4.  A  bus  is  an  IORelation  that  represents  multiple  channels.  It  is  indicated  by  a  relation  with  a 
slash  through  it,  and  the  number  adjacent  to  the  bus  is  the  width  of  the  bus. 


FIGURE  2.5.  Channels  may  reach  multiple  destinations.  This  is  represented  by  relations  linking  multiple 
input  ports  to  an  output  port. 
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destinations,  except  that  P8  does  not  send  to  itself.  Port  P3  has  width  zero,  so  its  send()  method  returns 
without  sending  the  token  anywhere.  Port  P6  has  width  two,  but  its  second  input  channel  has  no  output 
ports  connected  to  it,  so  calling  get(l)  will  trigger  an  exception  that  indicates  that  there  is  no  data.  Port 
P7  has  width  zero  so  calling  get()  with  any  argument  will  trigger  an  exception. 

2.2.3  Transparent  Ports 

Recall  that  a  port  is  transparent  if  its  container  is  transparent  (isOpaque()  returns  false).  A  Com- 
positeActor  is  transparent  unless  it  has  a  local  director.  Figure  2.7  shows  an  elaborate  example  where 
busses,  input,  and  output  ports  are  combined  with  transparent  ports.  The  transparent  ports  are  filled  in 
white,  and  again  arrows  indicate  the  direction  of  token  flow.  The  Jacl  code  to  construct  this  example  is 


FIGURE  2.6.  An  elaborate  example  showing  several  features  of  the  data  transport  mechanism. 


FIGURE  2.7.  An  example  showing  busses  combined  with  input,  output,  and  transparent  ports. 
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shown  in  figure  2.8. 

By  definition,  a  transparent  port  is  an  input  if  either 

•  it  is  connected  on  the  inside  to  the  outside  of  an  input  port,  or 

•  it  is  connected  on  the  inside  to  the  inside  of  an  output  port. 

That  is,  a  transparent  port  is  an  input  port  if  it  can  accept  data  (which  it  may  then  just  pass  through  to  a 
transparent  output  port).  Correspondingly,  a  transparent  port  is  an  output  port  if  either 

•  it  is  connected  on  the  inside  to  the  outside  of  an  output  port,  or 

•  it  is  connected  on  the  inside  to  the  inside  of  an  input  port. 

Thus,  assuming  PI  is  an  output  port  and  P7,  P8,  and  P9  are  input  ports,  then  P2,  P3,  and  P4  are  both 
input  and  output  ports,  while  P5  and  P6  are  input  ports  only. 

Two  of  the  relations  that  are  inside  composite  entities  (R1  and  R5)  are  labeled  as  busses  with  a  star 
(*)  instead  of  a  number.  These  are  busses  with  unspecified  width.  The  width  is  inferred  from  the  topol¬ 
ogy.  This  is  done  by  checking  the  ports  that  this  relation  is  linked  to  from  the  inside  and  setting  the 
width  to  the  maximum  of  those  port  widths,  minus  the  widths  of  other  relations  linked  to  those  ports  on 
the  inside.  Each  such  port  is  allowed  to  have  at  most  one  inside  relation  with  an  unspecified  width,  or 
an  exception  is  thrown.  If  this  inference  yields  a  width  of  zero,  then  the  width  is  defined  to  be  one. 
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FIGURE  2.8.  Tel  Blend  code  to  construct  the  example  in  figure  2.7. 
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Thus,  R1  will  have  width  4  and  R5  will  have  width  3  in  this  example.  The  width  of  a  transparent  port  is 
the  sum  of  the  widths  of  the  relations  it  is  linked  to  on  the  outside  (just  like  an  ordinary  port).  Thus,  P4 
has  width  0,  P3  has  width  2,  and  P2  has  width  4.  Recall  that  a  port  can  have  width  0,  but  a  relation  can¬ 
not  have  width  less  than  one. 

When  data  is  sent  from  PI,  four  distinct  channels  can  be  used.  All  four  will  go  through  P2  and  P5, 
the  first  three  will  reach  P8,  two  copies  of  the  fourth  will  reach  P9,  the  first  two  will  go  through  P3  to 
P7,  and  none  will  go  through  P4. 

By  default,  an  IORelation  is  not  a  bus,  so  its  width  is  one.  To  turn  it  into  a  bus  with  unspecified 
width,  call  setWidth()  with  a  zero  argument.  Note  that  getWidth()  will  nonetheless  never  return  zero  (it 
returns  at  least  one).  To  find  out  whether  setWidth()  has  been  called  with  a  zero  argument,  call 
isWidthFixed()  (see  figure  2.2).  If  a  bus  with  unspecified  width  is  not  linked  on  the  inside  to  any  trans¬ 
parent  ports,  then  its  width  is  one.  It  is  not  allowed  for  a  transparent  port  to  have  more  than  one  bus 
with  unspecified  width  linked  on  the  inside  (an  exception  will  be  thrown  on  any  attempt  to  construct 
such  a  topology).  Note  further  that  a  bus  with  unspecified  width  is  still  a  bus,  and  so  can  only  be  linked 
to  multiports. 

In  general,  bus  widths  inside  and  outside  a  transparent  port  need  not  agree.  For  example,  if  M  <  N 
in  figure  2.9,  then  first  M  channels  from  PI  reach  P3,  and  the  last  N-M  channels  are  dangling.  If 
M>N,  then  all  N  channels  from  PI  reach  P3,  but  the  last  M-N  channels  at  P3  are  dangling. 
Attempting  to  get  a  token  from  these  channels  will  trigger  an  exception.  Sending  a  token  to  these  chan¬ 
nels  just  results  in  loss  of  the  token. 

Note  that  data  is  not  actually  transported  through  the  relations  or  transparent  ports  in  Ptolemy  II. 
Instead,  each  output  port  caches  a  list  of  the  destination  receivers  (in  the  form  of  the  two-dimensional 
array  returned  by  getRemoteReceivers()),  and  sends  data  directly  to  them.  The  cache  is  invalidated 
whenever  the  topology  changes,  and  only  at  that  point  will  the  topology  be  traversed  again.  This  sig¬ 
nificantly  improves  the  efficiency  of  data  transport. 

2.2.4  Data  Transfer  in  Various  Models  of  Computation 

The  receiver  used  by  an  input  port  determines  the  communication  protocol.  This  is  closely  bound 
to  the  model  of  computation.  The  IOPort  class  creates  a  new  receiver  when  necessary  by  calling  its 
_newReceiver()  protected  method.  That  method  delegates  to  the  director  returned  by  getDirector(), 
calling  its  newReceiver()  method  (the  Director  class  will  be  discussed  in  section  2.3  below).  Thus,  the 
director  controls  the  communication  protocol,  in  addition  to  its  primary  function  of  determining  the 
flow  of  control.  Here  we  discuss  the  receivers  that  are  made  available  in  the  actor  package.  This  should 
not  be  viewed  as  an  exhaustive  set,  but  rather  as  a  particularly  useful  set  of  receivers.  These  receivers 
are  shown  in  figure  2.2. 


FIGURE  2.9.  Bus  widths  inside  and  outside  a  transparent  port  need  not  agree.. 
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Mailbox  Communication.  The  Director  base  class  by  default  returns  a  simple  receiver  called  a  Mail¬ 
box.  A  mailbox  is  a  receiver  that  has  capacity  for  a  single  token.  It  will  throw  an  exception  if  it  is 
empty  and  get()  is  called,  or  it  is  full  and  put()  is  called.  Thus,  a  subclass  of  Director  that  uses  this 
should  schedule  the  calls  to  put()  and  get()  so  that  these  exceptions  do  not  occur,  or  it  should  catch 
these  exceptions. 

Asynchronous  Message  Passing.  This  is  supported  by  the  QueueReceiver  class.  A  QueueReceiver  con¬ 
tains  an  instance  of  FIFOQueue,  from  the  actor.util  package,  which  implements  a  first-in,  first-out 
queue.  This  is  appropriate  for  all  flavors  of  dataflow  as  well  as  Kahn  process  networks. 


In  the  Kahn  process  networks  model  of  computation  [67],  which  is  a  generalization  of  dataflow  [87], 
each  actor  has  its  own  thread  of  execution.  The  thread  calling  get()  will  stall  if  the  corresponding  queue 
is  empty.  If  the  size  of  the  queue  is  bounded,  then  the  thread  calling  put()  may  stall  if  the  queue  is  full. 
This  mechanism  supports  implementation  of  a  strategy  that  ensures  bounded  queues  whenever  possi¬ 
ble  [125]. 

In  the  process  networks  model  of  computation,  the  histoiy  of  tokens  that  traverse  any  connection  is 
determinate  under  certain  simple  conditions.  With  certain  technical  restrictions  on  the  functionality  of 
the  actors  (they  must  implement  monotonic  functions  under  prefix  ordering  of  sequences),  our  imple¬ 
mentation  ensures  determinacy  in  that  the  history  does  not  depend  on  the  order  in  which  the  actors 
carry  out  their  computation.  Thus,  the  history  does  not  depend  on  the  policies  used  by  the  thread 
scheduler. 

FIFOQueue  is  a  support  class  that  implements  a  first- in,  first-out  queue.  It  is  part  of  the  actor.util 
package,  shown  in  figure  2.10.  This  class  has  two  specialized  features  that  make  it  particularly  useful 
in  this  context.  First,  its  capacity  can  be  constrained  or  unconstrained.  Second,  it  can  record  a  finite  or 
infinite  history,  the  sequence  of  objects  previously  removed  from  the  queue.  The  history  mechanism  is 
useful  both  to  support  tracing  and  debugging  and  to  provide  access  to  a  finite  buffer  of  previously  con¬ 
sumed  tokens. 

An  example  of  an  actor  definition  is  shown  in  figure  2.11.  This  actor  has  a  multiport  output.  It 
reads  successive  input  tokens  from  the  input  port  and  distributes  them  to  the  output  channels.  This 
actor  is  written  in  a  domain-polymorphic  way,  and  can  operate  in  any  of  a  number  of  domains.  If  it  is 


public  class  Distributor  extends  TypedAtomicActor  { 

public  TypedlOPort  _input; 
public  TypedlOPort  ^output; 

public  Distributor (CompositeActor  container,  String  name) 

throws  NameDuplicationException,  IllegalActionException  { 
super (container,  name); 

_input  =  new  TypedlOPort (this,  "input",  true,  false); 

_output  =  new  TypedlOPort (this,  "output",  false,  true); 

_output . setMultiport (true)  ; 

} 

public  void  fire()  throws  IllegalActionException  { 
for  (int  i=0;  i  <  _output . getwidth ( ) ;  i++)  { 

_output . send (i,  _input.get (0) ) ; 


FIGURE  2.1 1.  An  actor  that  distributes  successive  input  tokens  to  a  set  of  output  channels. 
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i  «interface» 

FIFOQueue 

Cloneable 

•  Comparator 

uj 

+INFINITE  CAPACITY  :  int  =  -1 

-_container :  Nameable 

j+compare(o1  :  Object,  o2  :  Object) :  int 

-_historyl_ist :  LinkedList 
-_queueCapacity :  int 
■_queueList :  LinkedList 


+FIFOQueue() 

+FIFOQueue(container :  Nameable) 
+FIFOQueue(model :  FIFOQueue) 
+clear() 

+elementList() :  List 
+get(offset :  int) :  Object 
+getCapacity() :  int 
+getContainer() :  Nameable 
+getHistoryCapacity() :  int 
+historyElementList() :  List 
+historySize() :  int 
+isFull() :  boolean 
+put(element :  Object) :  boolean 
+setCapacity(maxsize  :  int) 
+setContainer(container :  Nameable)| 
+setHistoryCapacity(capacity  :  int) 
+size() :  int 
+take() :  Object 


"'A” 


CQComparator 


+getVirtualBinNumber(entry  :  Object) :  long 
+setBinWidth(keyArray :  Object[j) 
+setZeroReference(zero  :  Object) 


7T 


+timeStamp  :  double 
+contents  :  Object 


+TimedEvent(time  :  double,  contents  :  Object) 


public  inner  class 


DoubleCQComparator 

_ i _ i _ 

TimedEvent.TimeComparator 

-_binWidth  :  Object 
-_zeroReference  :  Object 

-_binWidth  :  TimedEvent 
-_zeroReference  :  TimedEvent 

+DoubleCQComparator() 

_bucket :  CQLinkedListQ 
_n Buckets  :  int 
_qSize  :  int 


private  inner  class 


+CalendarQueue(comparator :  CQComparator) 

+CalendarQueue(comparator :  CQComparator,  minNumBuckets  :  int,  binCountFactor :  int)| 
+clear() 

+get() :  Object 

+includes(entry  :  Object) :  boolean 
+isEmpty() :  boolean 
put(entry  :  Object) :  boolean 
+remove(entry  :  Object) :  boolean 
+setAdaptive(flag  :  boolean) 

+size() :  int 
+take() :  Object 
+toArray() :  Object^ 

+toArray(limit :  int) :  Object^ 


+CQLinkedList() 

+first() :  Object 

+includes(obj :  Object) :  boolean| 
+isEmpty() :  boolean 
+insert(obj  :  Object) 

+remove(c  :  CQEntry) :  boolean 
+take() :  Object 


+find(element :  Object) :  CQCell 
+CQcell(element :  Object,  next :  CQCell)| 


FIGURE  2.10.  Static  structure  diagram  for  the  actor.util  package. 
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used  in  the  PN  domain,  then  its  input  will  have  a  QueueReceiver  and  the  output  will  be  connected  to 
ports  with  instances  QueueReceiver. 

Rendezvous  Communications.  Rendezvous,  or  synchronous  communication,  requires  that  the  origina¬ 
tor  of  a  token  and  the  recipient  of  a  token  both  be  simultaneously  ready  for  the  data  transfer.  As  with 
process  networks,  the  originator  and  the  recipient  are  separate  threads.  The  originating  thread  indicates 
a  willingness  to  rendezvous  by  calling  send(),  which  in  turn  calls  the  put()  method  of  the  appropriate 
receiver.  The  recipient  indicates  a  willingness  to  rendezvous  by  calling  get()  on  an  input  port,  which  in 
turn  calls  get()  of  the  designated  receiver.  Whichever  thread  does  this  first  must  stall  until  the  other 
thread  is  ready  to  complete  the  rendezvous. 

This  style  of  communication  is  implemented  in  the  CSP  domain.  In  the  receiver  in  that  domain,  the 
put()  method  suspends  the  calling  thread  if  the  get()  method  has  not  been  called.  The  get()  method  sus¬ 
pends  the  calling  thread  if  the  put()  method  has  not  been  called.  When  the  second  of  these  two  methods 
is  called,  it  wakes  up  the  suspended  thread  and  completes  the  data  transfer.  The  actor  shown  in  figure 
2. 1 1  works  unchanged  in  the  CSP  domain,  although  its  behavior  is  different  in  that  input  and  output 
actions  involve  rendezvous  with  another  thread. 

Nondeterministic  transfers  can  be  easily  implemented  using  this  mechanism.  Suppose  for  example 
that  a  recipient  is  willing  to  rendezvous  with  any  of  several  originating  threads.  It  could  spawn  a  thread 
for  each.  These  threads  should  each  call  get(),  which  will  suspend  the  thread  until  the  originator  is  will¬ 
ing  to  rendezvous.  When  one  of  the  originating  threads  is  willing  to  rendezvous  with  it,  it  will  call 
put().  The  multiple  recipient  threads  will  all  be  awakened,  but  only  one  of  them  will  detect  that  its  ren¬ 
dezvous  has  been  enabled.  That  one  will  complete  the  rendezvous,  and  others  will  die.  Thus,  the  first 
originating  thread  to  indicate  willingness  to  rendezvous  will  be  the  one  that  will  transfer  data.  Guarded 
communication  [7]  can  also  be  implemented. 

Discrete-Event  Communication.  In  the  discrete-event  model  of  computation,  tokens  that  are  trans¬ 
ferred  between  actors  have  a  time  stamp,  which  specifies  the  order  in  which  tokens  should  be  pro¬ 
cessed  by  the  recipients.  The  order  is  chronological,  by  increasing  time  stamp.  To  implement  this,  a 
discrete-event  system  will  normally  use  a  single,  global,  sorted  queue  rather  than  an  instance  of  FIFO- 
Queue  in  each  input  port.  The  kemel.util  package,  shown  in  figure  2. 1 0,  provides  the  CalendarQueue 
class,  which  gives  an  efficient  and  flexible  implementation  of  such  a  sorted  queue. 

2.2.5  Discussion  of  the  Data  Transfer  Mechanism 

This  data  transfer  mechanism  has  a  number  of  interesting  features.  First,  note  that  the  actual  trans¬ 
fer  of  data  does  not  involve  relations,  so  a  model  of  computation  could  be  defined  that  did  not  rely  on 
relations.  For  example,  a  global  name  server  might  be  used  to  address  recipient  receivers.  To  construct 
highly  dynamic  networks,  such  as  wireless  communication  systems,  it  may  be  more  intuitive  to  model 
a  system  as  an  aggregation  of  unconnected  actors  with  addresses.  A  name  server  would  return  a  refer¬ 
ence  to  a  receiver  given  an  address.  This  could  be  accomplished  simply  by  overriding  the  getRemoteR- 
eceivers()  method  of  IOPort  or  TypedlOPort,  or  by  providing  an  alternative  method  for  getting 
references  to  receivers.  The  subclass  of  IOPort  would  also  have  to  ensure  the  creation  of  the  appropri¬ 
ate  number  of  receivers.  The  base  class  relies  on  the  width  of  the  port  to  determine  how  many  receivers 
to  create,  and  the  width  is  zero  if  there  are  no  relations  linked. 

Note  further  that  the  mechanism  here  supports  bidirectional  ports.  An  IOPort  may  return  true  to 
both  the  islnput()  and  isOutputQ  methods. 
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2.3  Execution 

The  Executable  interface,  shown  in  figure  2.12,  is  implemented  by  the  Director  class,  and  is 
extended  by  the  Actor  interface.  An  actor  is  an  executable  entity.  There  are  two  types  of  actors,  Atom- 
icActor,  which  extends  ComponentEntity,  and  CompositeActor,  which  extends  CompositeEntity.  As 
the  names  imply,  an  AtomicActor  is  a  single  entity,  while  a  CompositeActor  is  an  aggregation  of 
actors.  Two  further  extensions  implement  a  type  system,  TypedAtomicActor  and  TypedCompositeAc- 
tor. 

The  Executable  interface  defines  how  an  object  can  be  invoked.  There  are  eight  methods.  The 
preinitialize()  method  is  assumed  to  be  invoked  exactly  once  during  the  lifetime  of  an  execution  of  a 
model  and  before  the  type  resolution  (see  the  type  system  chapter),  and  the  initialize()  methods  is 
assumed  to  be  invoked  once  after  the  type  resolution.  The  initialize()  method  may  be  invoked  again  to 
restart  an  execution,  for  example,  in  the  *-chart  model  (see  the  FSM  domain).  The  prefire(),  fire(),  and 
postfire()  methods  will  usually  be  invoked  many  times.  The  fire()  method  may  be  invoked  several 
times  between  invocations  of  prefire()  and  postfire().  The  stopFire()  method  is  invoked  to  request  sus¬ 
pension  of  firing.  The  wrapupQ  method  will  be  invoked  exactly  once  per  execution,  at  the  end  of  the 
execution. 

The  terminate()  method  is  provided  as  a  last-resort  mechanism  to  interrupt  execution  based  on  an 
external  event.  It  is  not  called  during  the  normal  flow  of  execution.  It  should  be  used  only  to  stop  run¬ 
away  threads  that  do  not  respond  to  more  usual  mechanism  for  stopping  an  execution. 

An  iteration  is  defined  to  be  one  invocation  of  prefire(),  any  number  of  invocations  of  fire(),  and 
one  invocation  of  postfire().  An  execution  is  defined  to  be  one  invocation  of  preinitialize(),  followed 
by  one  invocation  of  initialize(),  followed  by  any  number  of  iterations,  followed  by  one  invocation  of 
wrapupQ.  The  methods  preinitialize(),  initialize(),  prefire(),  fire(),  postfire(),  and  wrapupQ  are  called 
the  action  methods.  While,  the  action  methods  in  the  executable  interface  are  executed  in  order  during 
the  normal  flow  of  an  iteration,  the  terminateQ  method  can  be  executed  at  any  time,  even  during  the 
execution  of  the  other  methods. 

The  preinitializeQ  method  of  each  actor  gets  invoked  exactly  once.  Typical  actions  of  the  preini- 
tializeQ  method  include  creating  receivers  and  defining  the  types  of  the  ports.  Higher-order  function 
actors  should  construct  their  models  in  this  method.  The  preinitializeQ  method  cannot  produce  output 
data  since  type  resolution  is  typically  not  yet  done.  It  also  gets  invoked  prior  to  any  static  scheduling 
that  might  occur  in  the  domain,  so  it  can  change  scheduling  information. 

The  initializeQ  method  of  each  actor  gets  invoked  once  after  type  resolution  is  done.  It  may  be 
invoked  again  to  restart  the  execution  of  an  actor.  Typical  actions  of  the  initializeQ  method  include  cre¬ 
ating  and  initializing  private  data  members.  An  actor  may  produce  output  data  and  schedule  events  in 
this  method. 

The  prefireQ  method  may  be  invoked  multiple  times  during  an  execution,  but  only  once  per  itera¬ 
tion.  The  prefireQ  returns  true  to  indicate  that  the  actor  is  ready  to  fire.  In  other  words,  a  return  value  of 
true  indicates  “you  can  safely  invoke  my  fire  method,”  while  a  false  value  from  prefire  means  “My 
preconditions  for  firing  are  not  satisfied.  Call  prefire  again  later  when  conditions  have  change.”  For 
example,  a  dynamic  dataflow  actor  might  return  false  to  indicate  that  not  enough  data  is  available  on 
the  input  ports  for  a  meaningful  firing  to  occur. 

The  fireQ  method  may  be  invoked  multiple  times  during  an  iteration.  In  most  domains,  this 
method  defines  the  computation  performed  by  the  actor.  Some  domains  will  invoke  fireQ  repeatedly 
until  some  convergence  condition  is  reached.  Thus,  fireQ  should  not  change  the  state  of  the  actor. 
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«lnterface» 

Executable 


+COMPLETED  :  static  final  int 
+NOT  READY  :  static  final  int 
+STOP  ITERATING  :  static  final  inti 


+fire() 

+initialize() 

+iterate(count :  int) :  int 
+postfire() :  boolean 
+prefire() :  boolean 
+preinitialize() 
+stopFire() 

+terminate() 

+wrapup() 


A 


|#_currentTime  :  double 
container :  CompositeActor 


Attribute 

•  NamedObj 

b=3- 


~l  V 

«lnterface» 

Runnable 


+run() 


+Director() 

+Director(workspace  :  Workspace) 
+Director(container :  CompositeEntity,  name  :  String)| 
+fireAt(actor :  Actor,  time  :  double) 
+fireAtCurrentTime(actor :  Actor) 

+getCurrentTime() :  double 
+getNextlterationTime()  :  double 
+initialize(actor :  Actor) 

+invalidateResolvedTypes() 

+invalidateSchedule() 

+needWriteAccess() :  boolean 
+newReceiver() :  Receiver 
+requestChange(change  :  ChangeRequest) 
+requestlnitialization(actor :  Actor) 
+setCurrentTime(newTime  :  double) 

+stop() 

+transferlnputs(port :  lOPort)  :  boolean 
+transferOutputs(port :  lOPort)  :  boolean 
|#_writeAccessRequired()  :  boolean 


«lnterface» 

Actor 


+getDirector() :  Director 
+getExecutiveDirector() :  Director 
+getFunctionDependency() :  Function  Dependency 
+getManager() :  Manager 
+inputPortList() :  List 
+newReceiver() :  Receiver 
+outputPortList() :  List 


Manager.State 


-_description  :  String 


+getDescription()  :  String 
+getManager() :  Manager 
-State(description  :  String) 


j  ComponentEntity  \ 


KJ— 


i  CompositeEntity 


containee/A  0..1 


+DIRECTOR  :  int 


director :  Director 
|-_manager :  Manager 


AtomicActor 


+AtomicActor() 

+AtomicActor( workspace  :  Workspace) 

+AtomicActor( container :  CompositeEntity,  name  :  String)| 
+pruneDependencies() 

+removeDependency(input :  lOPort,  output :  lOPort) 


Manager 


+CORRUPTED  :  State 
+IDLE  :  State 
+INITIALIZING  :  State 
+ITERATING  :  State 
+MUTATING  :  State 
+PAUSED  :  State 
+PREINITIALIZING  :  State 
+RESOLVING  TYPES  :  State 


+WRAPPING  UP  :  State 
-_changeRequests  :  List 
-_container :  CompositeActor 
-_execution Listeners  :  List 
-_finishRequested  :  boolean 
-JterationCount :  int 
-_pauseReqested  :  boolean 
-_state  :  State 
-_thread  :  PtolemyThread 
-_typesResolved  :  boolean 
-_writeAccessNeeded  :  boolean 


+Manager() 

+Manager(name  :  String) 

+Manager(workspace  :  Workspace,  name  :  String) 
+addExecutionListener(listener :  ExecutionListener) 

+execute() 

+finish() 

+getlterationCount() :  int 
+getState()  :  State 
+initialize() 

+invalidateResolvedTypes() 

+iterate() :  boolean 

+notifyListenersOfException(ex  :  Exception) 

+pause() 

+removeExecutionListener(listener :  ExecutionListener) 
+requestChange(change  :  ChangeRequest) 

+requestlnitialization(actor :  Actor) 

+resolveTypes() 

+resume() 

+startRun() 

+timeAndMemory(startTime  :  long) :  String 

+timeAndMemorv(start :  long,  totalMem  :  long,  freeMem  :  long) :  String 


+wrapup() 

#_makeManagerOf(ca  :  CompositeActor) 
#_needWriteAccess() :  boolean 
#_notifyListenersOfCompletion() 
#_notifyListenersOfStateChange() 
#_processChangeRequests() 
#_setState(newState  :  State) 


CompositeActor 


+CompositeActor() 

+CompositeActor( workspace  :  Workspace) 
+CompositeActor(container :  CompositeEntity,  name  :  String) 
+allAtomicEntityList()  :  List 
newlnsideReceiver()  :  Receiver 
|+setDirector(director :  Director) 

+setManager(manager :  Manager) 


«lnterface» 

ExecutionListener 

StreamExecutionListener 

! - 1> 

+executionError(manager :  Manager,  exception :  Exception) 

+StreamExecutionListener() 

+executionFinished(manager :  Manager) 

+StreamExecutionListener(out :  OutputStream) 

+managerStateChanged(manager :  Manager) 

FIGURE  2.12.  Basic  classes  in  the  actor  package  that  support  execution. 
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Instead,  update  the  state  in  postfire(). 

In  opaque  composite  actors,  the  fire()  method  is  responsible  for  transferring  data  from  the  opaque 
ports  of  the  composite  actor  to  the  ports  of  the  contained  actors,  calling  the  fire()  method  of  the  direc¬ 
tor,  and  transferring  data  from  the  output  ports  of  the  composite  actor  to  the  ports  of  outside  actors.  See 
section  2.3.4  below. 

In  some  domains,  the  fire  method  initiates  an  open-ended  computation.  The  stopFire()  method 
may  be  used  to  request  that  firing  be  ended  and  that  the  fire()  method  return  as  soon  as  practical. 

The  postfire()  method  will  be  invoked  exactly  once  during  an  iteration,  after  all  invocations  of  the 
fire()  method  in  that  iteration.  An  actor  may  return  false  in  postfire  to  request  that  the  actor  should  not 
be  fired  again.  It  has  concluded  its  mission.  However,  a  director  may  elect  to  continue  to  fire  the  actor 
until  the  conclusion  of  its  own  iteration.  Thus,  the  request  may  not  be  immediately  honored. 

The  wrapupQ  method  is  invoked  exactly  once  during  the  execution  of  a  model,  even  if  an  excep¬ 
tion  causes  premature  termination  of  an  execution.  Typically,  wrapupQ  is  responsible  for  cleaning  up 
after  execution  has  completed,  and  perhaps  flushing  output  buffers  before  execution  ends  and  killing 
active  threads. 

The  terminate()  method  may  be  called  at  any  time  during  an  execution,  but  is  not  necessarily 
called  at  all.  When  terminate()  is  called,  no  more  execution  is  important,  and  the  actor  should  do  every¬ 
thing  in  its  power  to  stop  execution  right  away.  This  method  should  be  used  as  a  last  resort  if  all  other 
mechanisms  for  stopping  an  execution  fail. 

2.3.1  Director 

A  director  governs  the  execution  of  a  composite  entity.  A  manager  governs  the  overall  execution 
of  a  model.  An  example  of  the  use  of  these  classes  is  shown  in  figure  2.13.  In  that  example,  a  top-level 
entity,  EO,  has  an  instance  of  Director,  Dl,  that  serves  the  role  of  its  local  director.  A  local  director  is 
responsible  for  execution  of  the  components  within  the  composite.  It  will  perform  any  scheduling  that 
might  be  necessary,  dispatch  threads  that  need  to  be  started,  generate  code  that  needs  to  be  generated, 
etc.  In  the  example,  Dl  also  serves  as  an  executive  director  for  E2.  The  executive  director  associated 
with  an  actor  is  the  director  that  is  responsible  for  firing  the  actor. 

A  composite  actor  that  is  not  at  the  top  level  may  or  may  not  have  its  own  local  director.  If  it  has  a 
local  director,  then  it  defined  to  be  opaque  (isOpaque()  returns  true).  In  figure  2.13,  E2  has  a  local 
director  and  E3  does  not.  The  contents  of  E3  are  directly  under  the  control  of  Dl,  as  if  the  hierarchy 


M:  Manager 


Dl:  local  director 


EO 


FIGURE  2.13.  Example  application,  showing  a  typical  arrangement  of  actors,  directors,  and  managers. 
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were  flattened.  By  contrast,  the  contents  of  E2  are  under  the  control  of  D2,  which  in  turn  is  under  the 
control  of  Dl.  In  the  terminology  of  the  previous  generation,  Ptolemy  Classic,  E2  was  called  a  worm- 
hole.  In  Ptolemy  II,  we  simply  call  it  a  opaque  composite  actor.  It  will  be  explained  in  more  detail 
below  in  section  2.3.4. 

We  define  the  director  (vs.  local  director  or  executive  director)  of  an  actor  to  be  either  its  local 
director  (if  it  has  one)  or  its  executive  director  (if  it  does  not).  A  composite  actor  that  is  not  at  the  top 
level  has  as  its  executive  director  the  director  of  the  container.  Every  executable  actor  has  a  director 
except  the  top-level  composite  actor,  and  that  director  is  what  is  returned  by  the  getDirector()  method 
of  the  Actor  interface  (see  figure  2.12). 

When  any  action  method  is  called  on  an  opaque  composite  actor,  the  composite  actor  will  gener¬ 
ally  call  the  corresponding  method  in  its  local  director.  This  interaction  is  crucial,  since  it  is  domain- 
independent  and  allows  for  communication  between  different  models  of  computation.  When  fire()  is 
called  in  the  director,  the  director  is  free  to  invoke  iterations  in  the  contained  topology  until  the  stop¬ 
ping  condition  for  the  model  of  computation  is  reached. 

The  postfire()  method  of  a  director  returns  false  to  stop  its  execution  normally.  It  is  the  responsibil¬ 
ity  of  the  next  director  up  in  the  hierarchy  (or  the  manager  if  the  director  is  at  the  top  level)  to  conclude 
the  execution  of  this  director  by  calling  its  wrapupQ  method. 

The  Director  class  provides  a  default  implementation  of  an  execution,  although  specific  domains 
may  override  this  implementation.  In  order  to  ensure  interoperability  of  domains,  they  should  stick 
fairly  closely  to  the  sequence. 

Two  common  sequences  of  method  calls  between  actors  and  directors  are  shown  in  figure  2.14  and 
2.15.  These  differ  in  the  shaded  areas,  which  define  the  domain-specific  sequencing  of  actor  firings.  In 
figure  2.14,  the  fire()  method  of  the  director  selects  an  actor,  invokes  its  prefire()  method,  and  if  that 
returns  true,  invokes  its  fire()  method  some  number  of  times  (domain  dependent)  followed  by  its  post- 
fire()  method.  In  figure  2.15,  the  fire()  method  of  the  director  invokes  the  prefire()  method  of  all  the 
actors  before  invoking  any  of  their  fire()  methods. 

When  a  director  is  initialized,  via  its  initialize()  method,  it  invokes  initialize()  on  all  the  actors  in 
the  next  level  of  the  hierarchy,  in  the  order  in  which  these  actors  were  created.  The  wrapup()  method 
works  in  a  similar  way,  deeply  traversing  the  hierarchy.  In  other  words,  calling  initialize()  on  a  com¬ 
posite  actor  is  guaranteed  to  initialize  in  all  the  objects  contained  within  that  actor.  Similarly  for  wra- 
pup(). 

The  methods  prefire()  and  postfire(),  on  the  other  hand,  are  not  deeply  traversing  functions.  Call¬ 
ing  prefire()  on  a  director  does  not  imply  that  the  director  call  prefire()  on  all  its  actors.  Some  directors 
may  need  to  call  prefire()  on  some  or  all  contained  actors  before  being  able  to  return,  but  some  direc¬ 
tors  may  not  need  to  call  prefire()  on  any  contained  objects  at  all.  A  director  may  even  implement 
short-circuit  evaluation,  where  it  calls  prefire()  on  only  enough  of  the  contained  actors  to  determine  its 
own  return  value.  Postfire()  works  similarly,  except  that  it  may  only  be  called  after  at  least  one  suc¬ 
cessful  call  to  fire(). 

The  fire()  method  is  where  the  bulk  of  work  for  a  director  occurs.  When  a  director  is  fired,  it  has 
complete  control  over  execution,  and  may  initiate  whatever  iterations  of  other  actors  are  appropriate 
for  the  model  of  computation  that  it  implements.  It  is  important  to  stress  that  once  a  director  is  fired, 
outside  objects  do  not  have  control  over  when  the  iteration  will  complete.  The  director  may  not  iterate 
any  contained  actors  at  all,  or  it  may  iterate  the  contained  actors  forever,  and  not  stop  until  terminate() 
is  called.  Of  course,  in  order  to  promote  interoperability,  directors  should  define  a  finite  execution  that 
they  perform  in  the  fire()  method. 
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FIGURE  2.14.  Example  execution  sequence  implemented  by  run()  method  of  the  Director  class. 


Execution  Sequence:  Manager.run() 


Actor  Package 


Heterogeneous  Concurrent  Modeling  and  Design 


45 


FIGURE  2.15.  Alternative  execution  sequence  implemented  by  run()  method  of  the  Director  class. 
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In  case  it  is  not  practical  for  the  fire()  method  to  define  a  bounded  computation,  the  stopFire() 
method  is  provided.  A  director  should  respond  when  this  method  is  called  by  returning  from  its  fire() 
method  as  soon  as  practical. 

In  some  domains,  the  firing  of  a  director  corresponds  exactly  to  the  sequential  firing  of  the  con¬ 
tained  actors  in  a  specific  predetermined  order.  This  ordering  is  known  as  a  static  schedule  for  the 
actors.  Some  domains  support  this  style  of  execution.  There  is  also  a  family  of  domains  where  actors 
are  associated  with  threads. 

2.3.2  Manager 

While  a  director  implements  a  model  of  computation,  a  manager  controls  the  overall  execution  of 
a  model.  The  manager  interacts  with  a  single  composite  actor,  known  as  a  top  level  composite  actor. 
The  Manager  class  is  shown  in  figure  2.12.  Execution  of  a  model  is  implemented  by  three  methods, 
execute(),  run()  and  startRun().  The  startRun()  method  spawns  a  thread  that  calls  run(),  and  then  imme¬ 
diately  returns.  The  run()  method  calls  execute(),  but  catches  all  exceptions  and  reports  them  to  listen¬ 
ers  (if  there  are  any)  or  to  the  standard  output  (if  there  are  no  listeners). 

More  fine  grain  control  over  the  execution  can  be  achieved  by  calling  initialize(),  iterate(),  and 
wrapupQ  on  the  manager  directly.  The  execute()  method,  in  fact,  calls  these,  repeating  the  call  to  iter- 
ate()  until  it  returns  false.  The  iterate  method  invokes  prefire(),  fire()  and  postfire()  on  the  top-level 
composite  actor,  and  returns  false  if  the  postfire()  in  the  top-level  composite  actor  returns  false. 

An  execution  can  also  be  ended  by  calling  terminate()  or  finish()  on  the  manager.  The  terminate() 
method  triggers  an  immediate  halt  of  execution,  and  should  be  used  only  if  other  more  graceful  meth¬ 
ods  for  ending  an  execution  fail.  It  will  probably  leave  the  model  in  an  inconsistent  state,  since  it  works 
by  unceremoniously  killing  threads.  The  finish()  method  allows  the  system  to  continue  until  the  end  of 
the  current  iteration  in  the  top-level  composite  actor,  and  then  invokes  wrapup().  Finish()  encourages 
actors  to  end  gracefully  by  calling  their  stopFire()  method. 

Execution  may  also  be  paused  between  top-level  iterations  by  calling  the  pause()  method.  This 
method  sets  a  flag  in  the  manager  and  calls  stopFire()  on  the  top-level  composite  actor.  After  each  top- 
level  iteration,  the  manager  checks  the  flag.  If  it  has  been  set,  then  the  manager  will  not  start  the  next 
top-level  iteration  until  after  resume()  is  called.  In  certain  domains,  such  as  the  process  networks 
domain,  there  is  not  a  very  well  defined  concept  of  an  iteration.  Generally  these  domains  do  not  rely  on 
repeated  iteration  firings  by  the  manager.  The  call  to  stopFire()  requests  of  these  domains  that  they  sus¬ 
pend  execution. 

2.3.3  ExecutionListener 

The  ExecutionListener  interface  provides  a  mechanism  for  a  manager  to  report  events  of  interest  to 
a  user  interface.  Generally  a  user  interface  will  use  the  events  to  notify  the  user  of  the  progress  of  exe¬ 
cution  of  a  system.  A  user  interface  can  register  one  or  more  ExecutionListeners  with  a  manager  using 
the  method  addExecutionListener()  in  the  Manager  class.  When  an  event  occurs,  the  appropriate 
method  will  get  called  in  all  the  registered  listeners. 

Two  kinds  of  events  are  defined  in  the  ExecutionListener  interface.  A  listener  is  notified  of  the 
completion  of  an  execution  by  the  executionFinished()  method.  The  executionError()  method  indicates 
that  execution  has  ended  with  an  error  condition.  The  managerStateChangedQ  indicates  to  the  listener 
that  the  manager  has  changed  state.  The  new  state  can  be  obtained  by  calling  getState()  on  the  man¬ 
ager. 

A  default  implementation  of  the  ExecutionListener  interface  is  provided  in  the  StreamExecution- 
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Listener  class.  This  class  reports  all  events  on  the  standard  output. 

2.3.4  Opaque  Composite  Actors 

One  of  the  key  features  of  Ptolemy  II  is  its  ability  to  hierarchically  mix  models  of  computation  in  a 
disciplined  way.  The  way  that  it  does  this  is  to  have  actors  that  are  composite  (non-atomic)  and 
opaque.  Such  an  actor  was  called  a  wormhole  in  the  earlier  generation  of  Ptolemy.  Its  ports  are  opaque 
and  its  contents  are  not  visible  via  methods  like  deepEntityList(). 

Recall  that  an  instance  of  CompositeActor  that  is  at  the  top  level  of  the  hierarchy  must  have  a  local 
director  in  order  to  be  executable.  A  CompositeActor  at  a  lower  level  of  the  hierarchy  may  also  have  a 
local  director,  in  which  case,  it  is  opaque  (isOpaque()  returns  true).  It  also  has  an  executive  director, 
which  is  simply  the  director  of  its  container.  For  a  composite  opaque  actor,  the  local  director  and  exec¬ 
utive  director  need  not  follow  the  same  model  of  computation.  Hence  hierarchical  heterogeneity. 

The  ports  of  a  composite  opaque  actor  are  opaque,  but  it  is  a  composite  (it  can  contain  actors  and 
relations).  This  has  a  number  of  implications  on  execution.  Consider  the  simple  example  shown  in  fig¬ 
ure  2.16.  Assume  that  both  EO  and  E2  have  local  directors  (D1  and  D2),  so  E2  is  opaque.  The  ports  of 
E2  therefore  are  opaque,  as  indicated  in  the  figure  by  their  solid  fill.  Since  its  ports  are  opaque,  when  a 
token  is  sent  from  the  output  port  PI,  it  is  deposited  in  P2,  not  P5. 

In  the  execution  sequences  of  figures  2.14  and  2.15,  E2  is  treated  as  an  atomic  actor  by  Dl;  i.e.  D1 
acts  as  an  executive  director  to  E2.  Thus,  the  fire()  method  of  Dl  invokes  the  prefire(),  fire(),  and  post- 
fire()  methods  of  El,  E2,  and  E3.  The  fire()  method  of  E2  is  responsible  for  transferring  the  token  from 
P2  to  P5.  It  does  this  by  delegating  to  its  local  director,  invoking  its  transferlnputs()  method.  It  then 
invokes  the  fire()  method  of  D2,  which  in  turn  invokes  the  prefire(),  fire(),  and  postfire()  methods  of 
E4. 

During  its  fire()  method,  E2  will  invoke  the  fire()  method  of  D2,  which  typically  will  fire  the  actor 
E4,  which  may  send  a  token  via  P6.  Again,  since  the  ports  of  E2  are  opaque,  that  token  goes  only  as  far 
as  P3.  The  fire()  method  of  E2  is  then  responsible  for  transferring  that  token  to  P4.  It  does  this  by  dele¬ 
gating  to  its  executive  director,  invoking  its  transferOutputs()  method. 

The  CompositeActor  class  delegates  transfer  of  its  inputs  to  its  local  director,  and  transfer  of  its 
outputs  to  its  executive  director.  This  is  the  correct  organization,  because  in  each  case,  the  director 
appropriate  to  the  model  of  computation  of  the  destination  port  is  the  one  handling  the  transfer.  It  can 
therefore  handle  it  in  a  manner  appropriate  to  the  receiver  in  that  port. 


FIGURE  2.16.  An  example  of  an  opaque  composite  actor.  EO  and  E2  both  have  local  directors,  not  necessar¬ 
ily  implementing  the  same  model  of  computation. 
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Note  that  the  port  P3  is  an  output,  but  it  has  to  be  capable  of  receiving  data  from  the  inside,  as  well 
as  sending  data  to  the  outside.  Thus,  despite  being  an  output,  it  contains  a  receiver.  Such  a  receiver  is 
called  an  inside  receiver.  The  methods  of  IOPort  offer  only  limited  access  to  the  inside  receivers  (only 
via  the  getInsideReceivers()  method  and  getReceivers {relation),  where  relation  is  an  inside  linked 
relation). 

In  general,  a  port  may  be  both  an  input  and  an  output.  An  opaque  port  of  a  composite  opaque  actor, 
thus,  must  be  capable  of  storing  two  distinct  types  of  receivers,  a  set  appropriate  to  the  inside  model  of 
computation,  obtained  from  the  local  director,  and  a  set  appropriate  to  the  outside  model  of  computa¬ 
tion,  obtained  from  its  executive  director.  Most  methods  that  access  receivers,  such  as  hasToken()  or 
hasRoomQ,  refer  only  to  the  outside  receivers.  The  use  of  the  inside  receivers  is  rather  specialized, 
only  for  handling  composite  opaque  actors,  so  a  more  basic  interface  is  sufficient. 

2.4  Scheduler  and  Process  Support 

The  ptolemy.actor.util  package  shown  in  figure  2.10  provides  some  infrastructure  for  domain 
designers  by  supporting  efficient  queues  and  dependency  analysis.  In  addition,  the  actor  package  has 
two  other  subpackages,  actor.sched,  which  provides  rudimentary  support  for  domains  that  use  static 
schedulers  to  control  the  invocation  of  actors,  and  actor.process,  which  provides  support  for  domains 
where  actors  are  processes.  The  UML  diagrams  for  these  are  shown  in  figure  2.17  and  figure  2.18. 
This  section  describes  some  of  this  infrastructure. 

2.4.1  Function  Dependency 

The  FunctionDependency  class  and  its  subclasses  in  figure  2.10  provides  support  for  domains  that 
analyze  data  dependencies  for  scheduling  or  for  checking  correctness.  In  particular,  an  instance  of 
FunctionDependency  is  associated  with  every  actor  and  can  be  obtained  from  the  getFunctionDepen- 
decy()  method  of  the  Actor  interface  (see  figure  2.12).  The  instance  of  FunctionDependency  describes 
the  function  dependency  that  output  ports  of  the  associated  actor  have  on  its  input  ports.  An  output  port 
has  a  function  dependency  on  an  input  port  if  in  its  fire()  method,  it  sends  tokens  on  the  output  port  that 
depend  on  tokens  gotten  from  the  input  port. 

The  FunctionDependency  class  uses  a  graph  to  describe  the  function  dependency,  where  the  nodes 
of  the  graph  correspond  to  the  ports  and  an  edge  indicates  a  function  dependency.  The  edges  go  from 
input  ports  to  output  ports  that  depend  on  them.  For  atomic  actors,  this  function  dependency  graph  by 
default  indicates  that  each  output  port  depends  on  all  input  ports  (this  is  called  complete  dependency). 
For  some  atomic  actors,  such  as  the  TimedDelay  actor  in  the  DE  domain,  an  output  in  a  firing  does  not 
depend  on  an  input  port.  Such  actors  override  the  pruneDependencies()  method  of  AtomicActor  (see 
figure  2.12)  to  remove  dependencies  between  these  ports.  For  example,  the  TimedDelay  actor  of  the 
DE  domain  declares  that  its  output  port  is  independent  of  its  input  port  by  defining  this  method: 

public  void  pruneDependencies ( )  { 

super . pruneDependencies () ; 
removeDependency (input,  output) ; 

1 

For  composite  actors,  getFunctionDependency()  returns  an  instance  of  FunctionDependencyOf- 
CompositeActor  (see  figure  2.10).  This  class  provides  both  the  abstracted  view,  which  gives  the  func¬ 
tion  dependency  that  output  ports  of  the  actor  have  on  its  input  ports,  and  a  detailed  view  from  which  it 
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constructs  this  information.  The  detailed  view  is  a  graph  where  the  nodes  correspond  to  the  ports  of  the 
composite  actor  and  to  the  ports  of  all  deeply  contained  opaque  actors,  and  the  edges  represent  either 
the  communication  dependencies  implied  by  the  connections  within  the  composite  actor  or  the  func¬ 
tion  dependencies  of  the  contained  opaque  actors.  The  detailed  view  can  be  used  by  a  director  to  con¬ 
struct  a  schedule.  Also,  the  detailed  view  may  reveal  dependency  loops,  which  in  many  domains 
means  that  the  model  cannot  be  executed.  To  check  whether  there  are  such  loops,  use  the  getCycleNo- 
des()  method.  The  method  returns  an  array  of  IOPorts  in  such  loops,  of  an  empty  array  if  there  are  no 
such  loops. 

2.4.2  Statically  Scheduled  Domains 

The  Static  SchedulingDirector  class  extends  the  Director  base  class  to  add  a  scheduler.  The  sched¬ 
uler  (an  instance  of  the  Scheduler  class)  creates  an  instance  of  the  Schedule  class  which  represents  a 
statically  determined  sequence  of  actor  firings.  The  scheduler  also  caches  the  schedule  as  necessary 


FIGURE  2.17.  UML  static  structure  diagram  for  the  actor.sched  package. 
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until  it  is  invalidated  by  the  director.  This  means  that  domains  with  a  statically  determined  schedule 
(such  as  CT  and  SDF)  need  only  implement  the  action  methods  in  the  director  and  a  scheduler  with  the 
appropriate  scheduling  algorithm. 

The  Schedule  base  class  contains  a  list  of  schedule  elements,  each  with  a  repetitions  factor  that 
determines  the  number  of  times  that  element  will  be  repeated.  Since  a  schedule  itself  is  a  schedule  ele- 
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FIGURE  2.18.  UML  static  structure  diagram  for  the  actor.process  package. 
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ment,  schedules  can  be  defined  recursively.  Another  type  of  schedule  element  is  a  firing,  which  repre¬ 
sents  a  firing  of  a  single  actor.  An  iterator  over  all  firings  contained  by  a  schedule  is  returned  by  the 
firingIterator()  method  on  the  schedule.  In  the  iterator,  the  schedule  is  expanded  recursively,  with  each 
firing  repeated  the  appropriate  number  of  times.1 

2.4.3  Process  Domains 

Many  domains,  such  as  CSP,  PN  and  DDE,  consist  of  independent  processes  that  are  communicat¬ 
ing  in  some  way.  These  domains  are  collectively  termed  process  domains.  The  actor.process  package 
provides  the  following  base  classes  that  can  be  used  to  implement  process  domains. 

ProcessThread.  In  a  process  domain,  each  actor  represents  an  independently  executing  process.  In 
Ptolemy  II,  this  is  achieved  by  creating  a  separate  Java  thread  for  each  actor  [121][75].  Each  of  these 
threads  is  an  instance  of  ptolemy.actor.ProcessThread. 

The  thread  for  each  actor  is  started  in  the  prefire()  method  of  the  director.  After  starting,  this  thread 
repeatedly  calls  the  prefire(),  fire(),  and  postfire()  methods  of  its  associated  actor.  This  sequence  con¬ 
tinues  until  the  actor’s  postfire()  method  of  returns  false.  The  only  way  for  an  actor  to  terminate  grace¬ 
fully  in  PN  is  by  returning  from  its  fire()  method  and  then  returning  false  in  its  postfire()  method.  If  an 
actor  finishes  execution  as  above,  then  the  thread  calls  the  wrapupQ  method  of  the  actor.  Once  this 
method  returns,  the  thread  informs  the  director  about  the  termination  of  this  actor  and  finishes  its  own 
execution.  The  actor  will  not  be  fired  again  unless  the  director  creates  and  starts  a  new  thread  for  the 
actor. 

ProcessReceiver.  In  the  process  domains,  receivers  represent  the  communication  and  synchronization 
points  between  different  threads.  To  facilitate  creating  these  domains,  receivers  in  process  domains 
should  implement  the  ProcessReceiver  interface.  This  interface  provides  extended  information  about 
status  of  the  receiver,  and  the  threads  that  may  be  interacting  with  the  receiver. 

ProcessDirector  and  CompositeProcessDirector.  These  classes  are  base  classes  for  directors  in  the 
process-based  domains.  It  provides  some  basic  infrastructure  for  creating  and  managing  threads.  Most 
importantly,  it  provides  a  strategy  pattern  for  handling  deadlock  between  threads.  Subclasses  usually 
override  methods  in  this  class  to  handle  deadlock  in  a  domain-dependent  fashion.  In  order  to  detect 
deadlocks,  this  base  class  maintains  a  count  of  how  many  actors  in  the  system  are  executing  and  how 
many  are  blocked  for  some  reason.  This  method  of  detecting  deadlock  is  suggested  in  [74].  When  no 
threads  are  able  to  run,  the  director  calls  the  _resolveDeadlock()  method  to  attempt  to  resolve  the  dead¬ 
lock. 

The  initialize()  method  of  the  process  director  creates  the  receivers  in  the  input  ports  of  the  actors, 
creates  a  thread  for  each  actor  and  initializes  these  actors.  It  also  initializes  the  count  of  active  actors  in 
the  model  to  the  number  of  actors  in  the  composite  actor.  The  prefire()  method  starts  up  all  the  created 
threads.  This  method  returns  true  by  default.  The  fire()  method  of  a  process  director  does  not  actually 
fire  any  contained  actors.  Instead,  each  actor  is  iterated  by  its  associated  process  thread.  The  fire 
method  simply  blocks  the  calling  thread  until  deadlock  of  the  process  threads  occurs.  In  this  case,  the 
calling  thread  is  unblocked  and  the  fire  method  returns.  The  postfire()  method  simply  returns  true  if  the 
director  was  able  to  resolve  the  deadlock  at  the  end  of  the  fire  method,  or  false  otherwise.  Returning 
true  implies  that  if  some  new  data  is  provided  to  the  composite  actor  it  can  resume  execution.  Retum- 


1.  Note  that  creating  an  iterator  does  not  require  expanding  the  data  structure  of  the  schedule 
into  a  list  first. 
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ing  false  implies  that  this  composite  actor  will  not  be  fired  again.  In  that  case,  the  executive  director  or 
the  manager  will  call  the  wrapup()  method  of  the  top-level  composite  actor,  which  in  turn  calls  the 
wrapupQ  method  of  the  director.  This  causes  the  director  to  terminate  the  execution  of  the  composite 
actor. 

Introduction  to  Java  Threads.  The  process  domains,  like  the  rest  of  Ptolemy  II,  are  written  entirely  in 
Java  and  take  advantage  of  the  features  built  into  the  language.  In  particular,  they  rely  heavily  on 
threads  and  on  monitors  for  controlling  the  interaction  between  threads.  In  any  multi-threaded  environ¬ 
ment,  care  has  to  be  taken  to  ensure  that  the  threads  do  not  interact  in  unintended  ways,  and  that  the 
model  does  not  deadlock.  Note  that  deadlock  in  this  sense  is  a  bug  in  the  modeling  environment,  which 
is  different  from  the  deadlock  talked  about  before  which  may  or  may  not  be  a  bug  in  the  model  being 
executed. 

A  monitor  is  a  mechanism  for  ensuring  mutual  exclusion  between  threads.  In  particular  if  a  thread 
has  a  particular  monitor,  acquired  in  order  to  execute  some  code,  then  no  other  thread  can  simulta¬ 
neously  have  that  monitor.  If  another  thread  tries  to  acquire  that  monitor,  it  stalls  until  the  monitor 
becomes  available.  A  monitor  is  also  called  a  lock,  and  one  is  associated  with  every  object  in  Java. 

Code  that  is  associated  with  a  lock  is  defined  by  the  synchronized  keyword.  This  keyword  can 
either  be  in  the  signature  of  a  method,  in  which  case  the  entire  method  body  is  associated  with  that 
lock,  or  it  can  be  used  in  the  body  of  a  method  using  the  syntax: 

synchronized (object)  { 

...  //Part  of  code  that  requires  exclusive  lock  on  object 

} 

This  causes  the  code  inside  the  brackets  to  be  associated  with  the  lock  belonging  to  the  specified 
object.  In  either  case,  when  a  thread  tries  to  execute  code  controlled  by  a  lock,  it  must  either  acquire 
the  lock  or  stall  until  the  lock  becomes  available.  If  a  thread  stalls  when  it  already  has  some  locks, 
those  locks  are  not  released,  so  any  other  threads  waiting  on  those  locks  cannot  proceed.  This  can  lead 
to  deadlock  when  all  threads  are  stalled  waiting  to  acquire  some  lock  they  need. 

A  thread  can  voluntarily  relinquish  a  lock  when  stalling  by  calling  object.  wait()  where  object  is  the 
object  to  relinquish  and  wait  on.  This  causes  the  lock  to  become  available  to  other  threads.  A  thread 
can  also  wake  up  any  threads  waiting  on  a  lock  associated  with  an  object  by  calling  notify All()  on  the 
object.  Note  that  to  issue  a  notify All()  on  an  object  it  is  necessary  to  own  the  lock  associated  with  that 
object  first.  By  careful  use  of  these  methods  it  is  possible  to  ensure  that  threads  only  interact  in 
intended  ways  and  that  deadlock  does  not  occur. 

Approaches  to  locking  used  in  the  process  domains.  One  of  the  key  coding  patterns  followed  is  to 
wrap  each  wait()  call  in  a  while  loop  that  checks  some  flag.  Only  when  the  flag  is  set  to  false  can  the 
thread  proceed  beyond  that  point.  Thus  the  code  will  often  look  like 

synchronized (object)  { 

while (flag)  { 
ob j  ect . wait ( ) ; 

} 


} 
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The  advantage  to  this  is  that  it  is  not  necessary  to  worry  about  what  other  thread  issued  the  notify All() 
on  the  lock;  the  thread  can  only  continue  when  the  notifyAll()  is  issued  and  the  flag  has  been  set  to 
false. 

One  place  that  contention  between  threads  often  occurs  is  when  a  thread  tries  to  acquire  another 
lock  only  to  issue  a  notify All()  on  it.  To  reduce  the  contention,  it  often  easiest  if  the  notifyAll()  is 
issued  from  a  new  thread  which  has  no  locks  that  could  be  held  if  it  stalls.  This  is  often  used  in  the  CSP 
domain  to  wake  up  any  threads  waiting  on  receivers  after  a  pause  or  when  terminating  the  model.  The 
ptolemy .  actor .  process  .  Notif  yThread  class  can  be  used  for  this  purpose.  This  class  takes 
a  list  of  objects  in  a  linked  list,  or  a  single  object,  and  issues  a  notifyAll()  on  each  of  the  objects  from 
within  a  new  thread. 

Synchronization  Hierarchy.  Previously  we  have  discussed  how  model  deadlock  is  resolved  in  process 
domains.  Separate  from  these  notions  is  a  different  kind  of  deadlock  that  can  occur  in  a  modeling  envi¬ 
ronment  if  the  environment  is  not  designed  properly.  This  notion  of  deadlock  can  occur  if  a  system  is 
not  thread  safe.  Given  the  extensive  use  of  Java  threads  throughout  Ptolemy  II,  great  care  has  been 
taken  to  ensure  thread  safety;  we  want  no  bugs  to  exist  that  might  lead  to  deadlock  based  on  the  struc¬ 
ture  of  the  Ptolemy  II  modeling  environment.  Ptolemy  II  uses  monitors  to  guarantee  thread  safety.  A 
monitor  is  a  method  for  ensuring  mutual  exclusion  between  threads  that  both  have  access  to  a  given 
portion  of  code.  To  ensure  mutual  exclusion,  threads  must  acquire  a  monitor  (or  lock )  in  order  to 
access  a  given  portion  of  code.  While  a  thread  owns  a  lock,  no  other  threads  can  access  the  correspond¬ 
ing  code. 

There  are  several  objects  that  serve  as  locks  in  Ptolemy  II.  In  the  process  domains,  there  are  four 
primary  objects  upon  which  locking  occurs:  Workspace,  ProcessReceiver,  ProcessDirector  and  Atomi- 
cActor.  The  danger  of  having  multiple  locks  is  that  separate  threads  can  acquire  the  locks  in  competing 
orders  and  this  can  lead  to  deadlock.  A  simple  illustration  is  shown  in  figure  2.19.  Assume  that  both 
lock  A  and  lock  B  are  necessary  to  perform  a  given  set  of  operations  and  that  both  thread  1  and  thread 
2  want  to  perform  the  operations.  If  thread  1  acquires  A  and  then  attempts  to  acquire  B  while  thread  2 
does  the  reverse,  then  deadlock  can  occur. 

There  are  several  ways  to  avoid  the  above  problem.  One  technique  is  to  combine  locks  so  that 
large  sets  of  operations  become  atomic.  Unfortunately  this  approach  is  in  direct  conflict  with  the  whole 
purpose  behind  multi-threading.  As  larger  and  larger  sets  of  operations  utilize  a  single  lock,  the  limit  of 
the  corresponding  concurrent  program  is  a  sequential  program! 

Another  approach  is  to  adhere  to  a  hierarchy  of  locks.  A  hierarchy  of  locks  is  an  agreed  upon  order 
in  which  locks  are  acquired.  In  the  above  case,  it  may  be  enforced  that  lock  A  is  always  acquired  before 
lock  B.  A  hierarchy  of  locks  will  guarantee  thread  safety  [75]. 

Thread  1 

^~UjLock  A 
^"A^Lock  B 

Thread  2 


FIGURE  2.19.  Deadlock  Due  to  Unordered  Locking. 
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The  process  domains  have  an  unenforced  hierarchy  of  locks.  It  is  strongly  suggested  that  users  of 
Ptolemy  II  process  domains  adhere  to  this  suggested  locking  hierarchy.  The  hierarchy  specifies  that 
locks  be  acquired  in  the  following  order: 

Workspace  - >  ProcessReceiver  - >  ProcessDirector  - >  AtomicActor 

The  way  to  apply  this  rule  is  to  prevent  synchronized  code  in  any  of  the  above  objects  from  making  a 
call  to  code  that  is  to  the  left  of  the  object  in  question. 

There  is  one  further  rule  that  implementors  of  process  domains  should  be  aware  of.  A  thread 
should  give  up  all  the  read  permissions  on  the  workspace  before  calling  the  wait()  method  on  the 
receiver  object.  This  commonly  happens  in  the  get()  and  put()  methods  of  process  receivers,  which 
implement  the  synchronization  between  threads.  We  require  this  because  of  the  explicit  modeling  of 
mutual  exclusion  between  the  read  and  write  activities  on  the  workspace.  If  a  thread  holds  read  permis¬ 
sion  on  the  workspace  and  suspends  while  a  second  thread  requires  a  write  access  on  the  workspace 
before  performing  the  action  that  the  first  thread  is  waiting  for,  a  deadlock  results.  Furthermore,  a 
thread  must  also  regain  those  read  accesses  after  returning  from  the  call  to  the  wait()  method.  For  this  a 
wait(Object  object)  method  is  provided  in  the  class  Workspace  that  releases  read  accesses  on  the  work¬ 
space,  calls  wait()  on  the  argument  object,  and  regains  read  access  on  the  workspace  before  returning. 
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3.1  Introduction 

The  data  package  provides  data  encapsulation,  polymorphism,  parameter  handling,  an  expression 
language,  and  a  type  system.  Figure  3.1  shows  the  key  classes  in  the  main  package  (subpackages  will 
be  discussed  later). 

3.2  Data  Encapsulation 

The  Token  class  and  its  derived  classes  encapsulate  application  data.  Tokens  can  be  transported 
via  message  passing  between  Ptolemy  II  objects,  and  can  be  used  to  parameterize  Ptolemy  II  actors. 
Encapsulating  data  in  this  way  provides  a  standard  interface  so  that  data  can  be  handled  uniformly 
regardless  of  its  detailed  structure.  Such  encapsulation  allows  for  a  great  degree  of  extensibility,  per¬ 
mitting  developers  to  extend  the  library  of  data  types  that  Ptolemy  II  can  handle.  It  also  permits  a  user 
interface  to  interact  with  application  data  without  detailed  prior  knowledge  of  the  structure  of  the  data. 

Token  classes  are  provided  for  encapsulating  many  different  types  of  data,  such  as  integers 
(IntToken),  double  precision  floating  point  numbers  (DoubleToken),  and  complex  numbers  (Complex- 
Token).  A  special  Token  subclass  (EventToken)  exists  for  representing  the  presence  of  a  “pure  event” 
that  encapsulates  no  data.  Tokens  can  encapsulate  data  structures  of  arbitrary  size.  All  data  tokens 
share  several  properties,  including  immutability,  type-polymorphic  operations,  and  the  possibility  for 
automatic  type  conversions.  These  properties  will  be  described  in  later  sections. 
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«lnterface» 

Numerical 


#_unitCategoryExponents  :  int[] 


+ScalarToken() 

+absolute() :  ScalarToken 
+complexValue() :  Complex 
+doubleValue() :  double 
+fixValue() :  FixPoint 
+intValue() :  int 

+inUnitsOf(units  :  ScalarToken) :  ScalarToken 
+isLessThan(token  :  ScalarToken) :  BooleanToken 
+longValue() :  long 
+setUnitCategory(index :  int) 

+unitString() :  String 

#_addCategoryExponents(token  :  ScalarToken) :  int[] 
+_areUnitsEqual(scalarToken  :  ScalarToken) :  boolean 
#_copyOfCategoryExponents() :  int[] 

#_isUnitless() :  boolean 

#_subtractCategoryExponents(token  :  ScalarToken) :  int[] 


+Token() 

+add(rightArg  :  Token) :  Token 
+addReverse(leftArg  :  Token) :  Token 
+convert(token  :  Token) :  Token 
+divide(divisor :  Token) :  Token 
+divideReverse(dividend  :  Token) :  Token 
+getType() :  Type 

+isCloseTo(token  :  Token) :  BooleanToken 
|+isCloseTo(token  :  Token,  epsilon  :  double) :  BooleanToken 
isEqualTo(token  :  Token) :  BooleanToken 
|+modulo(rightArg  :  Token) :  Token 
+moduloReverse(leftArg  :  Token) :  Token 
|+multiply(rightFactor :  Token) :  Token 
|+multiplyReverse(leftFactor :  Token) :  Token 
+one() :  Token 

+subtract(rightArg  :  Token) :  Token 
+subtractReverse(leftArg  :  Token) :  Token 
|+zero() :  Token 


-_value :  Token[] 
-_elementType  :  Type 


+ArrayToken(value  :  Token[]) 
+ArrayToken(type  :  Type) 
+ArrayToken(init :  String) 
+arrayValue() :  Token[] 
+getElement(index  :  int) :  Token 
+length() :  int 


RecordToken 


-_fields  :  Map 


+RecordToken(labels  :  String [],  values  :  Token[])| 
+RecordToken(init :  String) 

+get(label :  String) :  Token 
+labelSet() :  Set 


StringToken 


■_value  :  String 
•_toString  :  String 


+StringToken() 
|+StringToken(value :  String) 
stringValue() :  String 


+FALSE  :  BooleanToken 
+TRUE  :  BooleanToken 


-  value  :  FixPoint 


+FixToken(value  :  double,  bits  :  int,  intBits  :  int) 
|+FixToken(value  :  double,  precision  :  Precision)| 
+FixToken(value  :  FixPoint) 

+FixToken(init :  String) 

+convertToDouble() :  double 
+print() 


BooleanToken 


-  value  :  boolean 


+BooleanToken() 
+BooleanToken(b  :  boolean)| 
+BooleanToken(init :  String) 
+booleanValue() :  boolean 
•not() :  BooleanToken 


ObjectToken 


_value  :  Object 


+ObjectToken() 
+ObjectToken(value  :  Object)| 
+getValue() :  Object 


ComplexToken 

LongToken 

-_value  :  Complex 

-_value  :  long 

+ComplexToken() 

+LongToken() 

+Complextoken(value  :  Complex) 

+LongToken(value  :  long) 

+LongToken(init :  String) 

l#DO  COPY  :  int 


#DO  NOT  COPY  :  int 


UnsignedByteToken 

DoubleToken 

IntToken 

-_value  :  long 

-_value  :  double 

-_value  :  int 

+UnsignedByteT  oken() 
+UnsignedByteToken(value  :  byte) 
+UnsignedByteToken(value  :  int) 
+UnsignedByteToken(init :  String) 
+byteValue() :  byte 
+unsignedConvert(value  :  byte) :  int 

+DoubleToken() 
+DoubleToken(value  :  double) 
+DoubleToken(init :  String) 

+lntToken() 
+lntToken(value  :  int) 
+lntToken(init :  String) 

+complexMatrix() :  Complex[][] 

+doubleMatrix() :  double[][] 

+getColumnCount() :  int 
+getElementAsToken(row  :  int,  col  :  int) :  Token 
getRowCount() :  int 
+intMatrix() :  int[][] 

+longMatrix() :  long[|[] 

+oneRight() :  Token 
toArray() :  ArrayToken 


BooleanMatrixToken 


columnCount :  int 
rowCount :  int 
_value  :  boolean[]Q 


+BooleanMatrixT  oken() 
+BooleanMatrixToken(value  :  boolean[][]) 
+BooleanMatrixToken(init :  String) 
+booleanMatrix() :  boolean[][| 
+getElementAt(row :  int,  column  :  int) :  boolean 


IntMatrixToken 


columnCount :  int 
|-_rowCount :  int 
•_value  :  intQQ 


+lntMatrixToken() 

+lntMatrixToken(value  :  int[][]) 

+lntMatrixToken(value  :  into,  C0Py  :  int) 
+lntMatrixToken(value  :  into, rows  :  int.  columns  :  int)| 
+lntMatrixToken(init :  String) 

+getElementAt(row  :  int,  col :  int) :  int 


-_columnCount :  int 
-_rowCount :  int 
-_value  :  long[][] 


+LongMatrixToken() 
+LongMatrixToken(value  :  long[][]) 
+LongMatrixToken(init :  String) 
+LongMatrixToke(value  :  long[]Q) 
+getElementAt(row  :  int,  col  :  int) :  long 


FixMatrixToken 


-_columnCount :  int 
-_precision  :  Precision 
-_rowCount :  int 
-_value  :  FixPoint[|[] 

+FixMatrixToken() 

+FixMatrixToken(value  :  FixPoint[][|) 
+FixMatrixToken(init :  String) 
+getElementAt(row  :  int,  column  :  int) :  FixPoint 
+fixMatrix() :  FixPoint[][] 


DoubleMatrixToken 


-_columnCount :  int 
-_rowCount :  int 
-_value  :  double[][] 

+DoubleMatrixToken() 

+DoubleMatrixToken(value  :  double[] []) 
+DoubleMatrixToken(value  :  double[][],  copy  :  int) 
+DoubleMatrixToken(init :  String) 
+getElementAt(row  :  int,  column  :  int) :  double 


ComplexMatrixToken 


-_columnCount :  int 
-_rowCount :  int 
-_value :  Complex[][] 

+ComplexMatrix() 

+ComplexMatrixToken(value  :  Complex[][]) 
+ComplexMatrixToken(value  :  Complex[j[],  copy  :  int) 
+ComplexMatrixToken(init :  String) 
+getElementAt(row  :  int,  column  :  int) :  Complex 
#_getlnternalComplexMatrix() :  Complex[][] 


FIGURE  3.1.  Static  Structure  Diagram  (Class  Diagram)  for  the  classes  in  the  data  package. 
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3.2.1  Matrix  data  types 

The  MatrixToken  base  class  provides  basic  structure  for  two-dimensional  arrays  of  data.  Various 
derived  classes  encapsulate  data  of  different  types,  such  as  integers,  and  complex  numbers.  Standard 
matrix-matrix  and  scalar-matrix  operations  are  defined. 

3.2.2  Array  and  Record  data  types 

An  Array  Token  is  a  token  that  contains  an  array  of  tokens.  All  the  element  tokens  must  have  the 
same  type,  but  that  type  is  arbitrary.  For  instance,  it  is  possible  to  constructs  arrays  of  arrays  of  any 
type  of  token.  The  Array  Token  class  differs  from  the  various  MatrixToken  classes  in  that  MatrixTo- 
kens  contain  only  be  constructed  for  primitive  data,  such  as  int  or  double,  while  an  array  can  be  con¬ 
structed  for  arbitrary  token  types.  In  other  words,  matrix  tokens  are  specialized  for  storing  two 
dimensional  structures  of  primitive  data,  while  array  tokens  offer  more  flexibility  in  type  specifica¬ 
tions. 

A  RecordToken  contains  a  set  of  labeled  values,  and  operates  similarly  to  struct  in  the  C  lan¬ 
guage.  The  values  can  be  arbitrary  tokens  and  are  not  required  to  have  the  same  type. 

3.2.3  Fixed  Point  Data  Type 

The  FixToken  class  encapsulates  fixed  point  data.  The  UML  diagram  showing  classes  involved  in 
the  definition  of  the  FixPoint  data  type  is  shown  in  Figure  3.2.  The  FixToken  class  encapsulates  an 
instance  of  the  FixPoint  class  in  the  math  package.  The  underlying  FixPoint  class  is  implemented  using 
Java’s  Biglnteger  class  to  represent  fixed  point  values.  The  advantage  of  using  the  Biglnteger  package 
is  that  it  makes  this  FixPoint  implementation  truly  platform  independent  and  furthermore,  it  doesn’t 
put  any  restrictions  on  the  maximal  number  of  bits  allowed  to  represent  a  value. 

The  precision  of  a  FixPoint  data  type  is  represented  by  the  Precision  class.  This  class  does  the 
parsing  and  validation  of  the  various  specification  styles  we  want  to  support.  It  stores  a  precision  into 
two  separate  integers.  One  number  represents  the  number  of  integer  bits,  and  the  other  number  repre¬ 
sents  the  number  of  fractional  bits.  For  convenience,  the  precision  of  fixed  point  data  can  be  specified 
in  two  different  ways: 

(, m/n):  The  total  precision  of  the  output  is  m  bits,  with  the  integer  part  having  n  bits.  The  fractional 

part  thus  has  m  -  n  bits. 

(»?./;):  The  total  precision  of  the  output  is  n  +  m  bits,  with  the  integer  part  having  m  bits,  and  the 
fractional  part  having  n  bits. 

The  Quantization  class  represents  various  quantization  techniques.  Creating  a  FixPoint  value 
requires  specifying  a  double  value  and  an  instance  of  the  Quantization  class.  For  convenience,  static 
methods  are  provided  in  the  Quantizer  class  that  create  FixPoint  instances  without  referencing  a  Quan¬ 
tization  explicitly.  During  conversion,  the  handling  of  overflow  and  underflow  is  handled  by  specify¬ 
ing  instances  of  the  Overflow  class. 

The  convertToDouble()  method  in  the  FixToken  class  converts  a  fixed  point  value  into  a  double 
representation.  Note  that  the  getDouble()  method  defined  by  Token  is  not  used  since  conversion  from 
a  FixPoint  to  a  double  is  not,  in  general,  a  lossless  conversion  and  is  hence  not  allowed  automatically. 
For  details  about  how  to  represent  Fixed  Point  numbers  in  the  expression  language,  see  volume  1,  the 
Expressions  chapter. 
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ptolemy.data.expr.FixPointFunctions 


"  +fix(value  :  double,  numberOfBits  :  int,  integerBits  :  int) :  Token 
+fix(value  :  int,  numberOfBits  :  int,  inteqerBits  :  int) :  Token 

+fix(values  :  DoubleMatrixToken,  numberOfBits  :  int,  integerBits  :  int) :  FixMatrixToken 


+quantize(value  :  double,  numberOfBits  :  int,  inteqerBits  :  int) :  DoubleToken 
+quantize(values  :  DoubleMatrixToken,  numberOfBits  :  int,  inteqerBits  :  int) :  DoubleMatrixTokenl 


1 . 

ptolemy.data.ScalarToken 

ptolemy.data.  MatrixToken 

m 


ptolemy.data.FixToken 


value  :  FixPoint 


+FixToken(value  :  FixPoint) 

+FixToken(value  :  double,  precision  :  String) 

+FixToken(value  :  double,  numberOfBits  :  int,  integerBits  :  int) 
+FixToken(init :  String) 

+convertToDouble() :  double 
+fixValue() :  FixPonit 


ptolemy.data. FixMatrixToken 


columnCount :  int 
precision  :  Precision 
|-_rowCount :  int 
-_value  :  FixPointQ[] 


+FixMatrixToken() 

+FixMatrixToken(value  :  FixPoint[][]) 
+FixMatrixToken(init :  String) 

+fixMatrix() :  FixPoint[][] 

+getElementAt(row  :  int,  column  :  int) :  FixPointl 


ptolemy.data.expr.PtParser 


;+registerFunctionClass(newClassName  :  String) 


NxM 


1..1 


ptolemy.math. FixPoint 


+NOOVERFLOW  :  Error 
+OVERFLOW  :  Error 


+ROUNDING  :  Error 


-_precision  :  Precision 
-_value  :  Biglnteger 


FixPoint(precision  :  Precision,  value  :  Biglnteger) 
+abs() :  FixPoint 
+add(arg  :  FixPoint) :  FixPoint 
+bigDecimalValue() :  BigDecimal 
+divide(arg  :  FixPoint) :  FixPoint 
+doubleValue() :  double 
+equals(arg  :  FixPoint) :  boolean 
+getError() :  Error 
+getPrecision() :  Precision 
+multiply(arg  :  FixPoint) :  FixPoint 
+subtract(arg  :  FixPoint) :  FixPoint 
+toBitString() :  String 


T 


ptolemy.math. Precision 


■Jength  :  int 
■JntegerBits  :  int 
■  fraction  :  int 


+Precision(precision  :  String) 

+Precision(length  :  int,  integerBits  :  int) 

+findMaximum() :  BigDecimal 
+findMinimum() :  BigDecimal 
+getFractionBitLength() :  int 
+getlnegerBitLength() :  int 
+getNumberOfBits() :  int 

+matchThePoint(precisionA  :  Precision,  PrecisionB  :  Precision) :  Precision 


«U$es» 


TT7T 


1..1 


ptolemy.math. FixPoint.FixValue 


+fixvalue  :  Biglnteger 
-  error :  Error 


+FixValue() 

+FixValue(value  :  Biglnteger,  error :  Error) 

+abs() :  FixValue 
+add(value  :  FixValue) :  FixValue 
+getError() :  Error 

+getFractionBits(precision  :  Precision) :  FixValue| 
+getlntegerBits(precision  :  Precision) :  FixValue 
+multiply(value  :  FixValue) :  FixValue 
+negate() :  FixValue 
scaleLeft(delta  :  int) :  FixValue 
+scaleRight(delta  :  int) :  FixValue 
+setError(error :  Error) 


Uses  for]  division 


ptolemy.math. Quantizer 

+OVERFLOW  TO  ZERO  :  int 

+SATURATE  :  int 

+round(value  :  BiqDecimal,  precision  :  Precision) :  FixPoint 

+round(value  :  double,  precision  :  Precision) :  FixPoint 

+round(value  :  FixPoint,  newprecision  :  Precision,  mode  :  int) :  FixPoint 

+roundDown(value  :  BiqDecimal,  precision  :  Precision) :  FixPoint 

+roundDown(value  :  double,  precision  :  Precision) :  FixPoint 

+roundDown(value  :  FixPoint,  newPrecision  :  precision) :  FixPoint 

+roundNearestEven(value  :  BiqDecimal,  precision  :  Precision) :  FixPoint 

+roundNearestEven(value  :  double,  precision  :  Precision) :  FixPoint 

+roundNearestEven(value  :  FixPoint,  newPrecision  :  Precision,  mode  :  int) :  FixPoint 

+roundToZero(value  :  BiqDecimal,  precision  :  Precision) :  FixPoint 

+roundToZero(value  :  double,  precision  :  Precision) :  FixPoint 

+roundToZero(value  :  FixPoint,  newPrecision  :  Precision,  mode  :  int) :  FixPoint 

+roundUp(value  :  double,  precision  :  Precision) :  FixPoint 

+roundUp(value  :  BiqDecimal,  precision  :  Precision) :  FixPoint 

+roundUp(value  :  FixPoint,  newprecision  :  Precision,  mode  :  int) :  FixPoint 

«Usies» 


ijava.  math.  BigDecimal! 


•java.  math.  Biglnteger  j 


ptolemy.math.  FixPoint.Error| 

--description  :  String 
+Error(description  :  String) 

-  +getDescription() :  String 


FIGURE  3.2.  Organization  of  the  FixPoint  Data  Type. 
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3.2.4  Function  Closures 

The  FunctionToken  class  encapsulates  functions  that  can  be  evaluated.  These  function  closures  can 
be  passed  as  messages  just  like  any  other  tokens.  When  a  function  closure  is  created,  all  identifiers  that 
are  not  arguments  to  the  function  are  evaluated.  The  arguments  to  the  function,  however  are  only  eval¬ 
uated  when  the  function  is  applied.  For  information  on  how  functions  closures  can  be  represented  in 
the  expression  language,  see  volume  1 . 

3.2.5  Nil  Tokens 

Null  or  missing  tokens  are  common  in  analytical  systems  like  R  and  SAS  where  they  are  used  to 
handle  sparsely  populated  data  sources.  In  database  parlance,  missing  tokens  are  sometimes  called 
null  tokens.  Since  null  is  a  Java  keyword,  we  use  the  term  "nil".  Nil  tokens  are  useful  for  analyzing 
real  world  data  such  as  temperature  where  the  value  was  not  measured  during  every  interval.  In  princi¬ 
ple,  an  as  yet  unimplemented  function  such  as  average()  could  properly  handle  nil  tokens  -  when  the 
average()  method  sees  a  nil  token,  it  should  be  ignored.  Note  that  this  can  lead  to  uncertainty.  For 
example,  if  average()  is  expecting  30  values  and  29  of  them  are  nil,  then  the  average  will  not  be  very 
accurate. 

If  an  operation  such  as  add(),  divide(),  modulo(),  multiply(),  one(),  subtract(),  zero()  or  their  corre¬ 
sponding  “reverse”  operations  includes  a  nil  token,  then  the  output  is  nil.  If  one  of  the  arguments  for 
isCloseTo()  or  isEqualTo()  is  nil,  then  the  method  returns  false.  Methods  that  return  a  nil  token  return  a 
nil  token  with  a  specific  type  so  that  type  safety  is  preserved.  The  following  tokens  have  NIL  values 
defined:  Array  Type,  BooleanToken,  ComplexToken,  DoubleToken,  IntToken,  LongToken,  StringTo- 
ken,  Token,  UnsignedByteToken.  There  is  no  nil  token  for  the  various  matrix  tokens  because  the 
underlying  matrices  are  java  native  type  matrices  that  do  not  support  nil. 

3.3  Immutability 

Tokens  in  Ptolemy  II  are,  in  general,  immutable.  This  means  that  a  token’s  value  cannot  be 
changed  after  the  token  is  constructed.  The  value  of  a  token  must  be  specified  by  constructor  argu¬ 
ments,  and  there  is  no  other  mechanism  for  setting  the  value.  If  a  token  encapsulating  another  value  is 
required,  a  new  instance  of  Token  must  be  constructed. 

There  are  several  reasons  for  making  tokens  immutable. 

•  First,  when  a  token  is  sent  to  several  receivers,  we  want  to  be  sure  that  all  receivers  get  the  same 
data.  Each  receiver  is  sent  a  reference  to  the  same  token.  If  the  Token  were  not  immutable,  then  it 
would  be  necessary  to  clone  the  token  for  all  receivers  after  the  first  one. 

•  Second,  since  a  token  is  passed  between  two  actors,  they  may  both  have  a  reference  to  the  token.  If 
the  token  were  mutable,  then  the  token  would  represent  shared  state  of  the  two  actors,  requiring 
synchronization  and  limiting  the  ability  to  represent  distributed  computation.  Immutable  tokens 
passed  between  actors  ensures  that  the  concurrency  of  actors  is  determined  solely  by  a  model  of 
computation. 

•  Third,  we  use  tokens  to  parameterize  actors,  and  parameters  often  have  mutual  dependencies.  That 
is,  the  value  of  a  parameter  may  depend  on  the  value  of  other  parameters.  The  value  of  a  parameter 
is  represented  by  an  instance  of  Token.  If  that  token  were  allowed  to  change  value  without  notify¬ 
ing  the  parameter,  then  the  parameter  would  not  be  able  to  notify  other  parameters  that  depend  on 
its  value.  Thus,  a  mutable  token  would  have  to  implement  a  publish-and-subscribe  mechanism  so 
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that  parameters  could  subscribe  and  thus  be  notified  of  any  changes.  By  making  tokens  immutable, 
we  greatly  simplify  the  design. 

•  Finally,  having  our  Tokens  immutable  makes  them  similar  in  concept  to  the  data  wrappers  in  Java, 
like  Double,  Integer,  etc.,  which  are  also  immutable. 

In  most  cases,  the  immutability  of  tokens  is  enforced  by  the  design  of  the  Token  subclasses.  One 
exception  is  the  ObjectToken  class.  An  ObjectToken  contains  a  reference  to  an  arbitrary  Java  object 
created  by  the  user,  and  a  reference  to  this  object  can  be  retrieve  through  the  getValue()  method.  Since 
the  user  may  modify  the  object  after  the  token  is  constructed,  the  immutability  of  an  ObjectToken  is 
difficult  to  ensure.  Although  it  could  be  possible  to  clone  the  object  in  the  ObjectToken  constructor 
and  return  another  clone  in  the  getValue()  method,  this  would  require  the  object  to  be  cloneable, 
severely  limiting  the  use  of  the  ObjectToken.  In  addition,  since  the  default  implementation  of  clone() 
only  makes  a  shallow  copy,  this  approach  is  not  able  to  enforce  immutability  on  all  cloneable  objects. 
Cloning  a  large  object  could  be  prohibitively  expensive.  For  these  reasons,  the  ObjectToken  does  not 
attempt  to  enforce  immutability,  but  rather  relies  on  the  cooperation  from  the  user.  Violating  this  con¬ 
vention  could  lead  to  unintended  non-determinism. 

For  matrix  tokens,  enforced  immutability  requires  the  contained  matrix  (Java  array)  to  be  copied 
when  the  token  is  constructed  and  when  the  matrix  is  returned  in  response  to  queries  such  as  intMa- 
trix(),  doubleMatrix(),  etc.  Since  the  cost  of  copying  large  arrays  is  non-trivial,  the  user  should  not 
make  more  queries  than  necessary.  For  optimization,  some  matrix  token  classes  have  a  constructor  that 
takes  a  flag,  which  specifies  whether  the  given  array  needs  to  be  copied  or  not.  The  getElementAt() 
method  can  be  used  to  read  the  contents  of  the  matrix  without  copying  the  internal  array. 

3.4  Polymorphism 

3.4.1  Polymorphic  Arithmetic  Operators 

One  of  the  goals  of  the  data  package  is  to  support  polymorphic  operations  between  tokens.  For 
this,  the  base  Token  class  defines  methods  for  primitive  arithmetic  operations,  which  are  add(),  multi- 
ply(),  subtract(),  divide(),  modulo()  and  equals().  Derived  classes  override  these  methods  to  provide 
class  specific  operation  where  appropriate.  The  objective  here  is  to  be  able  to  say,  for  example, 

a . add (b) 

where  a  and  b  are  arbitrary  tokens.  If  the  operation  a  +  b  makes  sense  for  the  particular  tokens,  then 
the  operation  is  carried  out  and  a  token  of  the  appropriate  type  is  returned.  If  the  operation  does  not 
make  sense,  then  an  exception  is  thrown.  Consider  the  following  example 

IntToken  a  =  new  IntToken(5); 

DoubleToken  b  =  new  DoubleToken (2 . 2 ) ; 

StringToken  c  =  new  StringToken ( "hello" ) ; 


then 

a . add (b) 

gives  a  new  DoubleToken  with  value  7.2, 

a . add (c) 

gives  a  new  StringToken  with  value  “5Hello”,  and 
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a .modulo (c) 

throws  an  exception.  Thus  in  effect  we  have  overloaded  the  operators  +,  *,  /,  %,  and  ==. 

It  is  not  always  immediately  obvious  what  is  the  correct  implementation  of  an  operation  and  what 
the  return  type  should  be.  For  example,  the  result  of  adding  an  integer  token  to  a  double-precision 
floating-point  token  should  probably  be  a  double,  not  an  integer.  The  mechanism  for  making  such 
decisions  depends  on  a  type  hierarchy  that  is  defined  separately  from  the  class  hierarchy.  This  type 
hierarchy  is  explained  below. 

The  token  classes  also  implement  the  methods  zero()  and  one()  which  return  the  additive  and  mul¬ 
tiplicative  identities  respectively.  These  methods  are  overridden  so  that  each  token  type  returns  a  token 
of  its  type  with  the  appropriate  value.  For  matrix  tokens,  zero()  returns  a  zero  matrix  whose  dimension 
is  the  same  as  the  matrix  of  the  token  where  this  method  is  called;  and  one()  returns  the  left  identity, 
i.e.,  it  returns  an  identity  matrix  whose  dimension  is  the  same  as  the  number  of  rows  of  the  matrix  of 
the  token.  Another  method  oneRight()  is  also  provided  in  numerical  matrix  tokens,  which  returns  the 
right  identity,  i.e.,  the  dimension  is  the  same  as  the  number  of  columns  of  the  matrix  of  the  token. 

Since  data  is  transferred  between  entities  using  Tokens,  it  is  straightforward  to  write  polymorphic 
actors  that  receive  tokens  on  their  inputs,  perform  one  or  more  of  the  overloaded  operations  and  output 
the  result.  For  example  an  add  actor  that  looks  like  this: 


might  contain  code  like: 

Token  inputl,  input2,  output; 

//  read  Tokens  from  the  input  channels  into  inputl  and  input2  variables 

output  =  inputl . add ( input2 ) ; 

//  send  the  output  Token  to  the  output  channel. 

We  call  such  actors  data  polymorphic  to  contrast  them  from  domain  polymorphic  actors,  which  are 
actors  that  can  operate  in  multiple  domains.  Of  course,  an  actor  may  be  both  data  and  domain  polymor¬ 
phic. 

3.4.2  Automatic  Type  Conversion 

For  the  above  arithmetic  operations,  if  the  two  tokens  being  operated  on  have  different  types,  type 
conversion  is  needed.  Generally  speaking,  Ptolemy  II  automatically  performs  conversions  that  do  not 
lose  numerical  precision.  Other  conversion  must  be  explicitly  represented  by  the  user.  The  admissible 
automatic  type  conversions  between  different  token  types  are  modeled  as  a  partially  ordered  set  called 
the  type  lattice,  shown  in  figure  3.3.  In  that  diagram,  type  A  is  greater  than  type  B  if  there  is  a  path 
upwards  from  B  to  A.  Thus,  [ complex ]  (a  complex  matrix)  is  greater  than  int.  Type  A  is  less  than  type  B 
if  there  is  a  path  downwards  from  B  to  A.  Thus,  int  is  less  than  [complex].  Otherwise,  types  A  and  B  are 
incomparable.  Types  complex  and  long,  for  example,  are  incomparable.  In  the  type  lattice,  a  type  can 
be  automatically  converted  to  any  type  greater  than  it. 

This  hierarchy  is  realized  by  the  TypeLattice  class  in  the  data.type  subpackage.  Each  node  in  the 
lattice  is  an  instance  of  the  Type  interface.  The  TypeLattice  class  provides  methods  to  compare  two 
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token  types. 

Two  of  the  types,  matrix  and  scalar,  are  union  types.  This  means  that  an  instance  of  this  type  can 
be  any  of  the  types  immediately  below  them  in  the  lattice.  Recall  that  arrays  always  have  entries  with 
the  same  type.  If  that  type  is  matrix  or  scalar,  then  the  array  may  appear  to  have  multiple  types.  For 
example,  in  the  expression  evaluator, 

»  {1,  2.3} 

{1.0,  2.3} 

»  {1,  2.3,  true} 

{ 1 ,  2.3,  true } 

In  the  first  case,  the  least  common  type  is  double,  so  the  elements  are  all  converted  to  double.  In  the 
second  case,  the  least  common  element  is  scalar,  so  the  elements  are  all  converted  to  scalar,  which  in 
this  example  results  in  no  conversion!  To  see  that  the  type  of  the  array  is  {scalar},  do  this, 


»  {1,  2.3,  true } . getType ( ) 


General 


FIGURE  3.3.  The  type  lattice. 
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object({scalar}) 

(The  return  value  of  getType()  is  not  a  Token,  so  the  expression  evaluator  wraps  it  in  an  ObjectToken, 
which  displays  its  value  as  “object(toSr/«g())”.) 

Similarly,  for  matrices, 

»  { [int] ,  [double] } 

{[0.0],  [0.0]] 

»  { [long] ,  [double] } 

{[0L],  [0.0]} 

»  {[long],  [double] }. getType  ( ) 
object ( {matrix} ) 

Type  conversion  is  done  by  the  convert()  method  in  type  classes.  This  method  converts  the  argu¬ 
ment  into  a  token  with  the  same  type.  For  example,  BaseType.DoubleType.convert(Token  token)  con¬ 
verts  the  specified  token  into  an  instance  of  DoubleToken.  The  convert()  method  can  convert  any 
token  immediately  below  it  in  the  type  hierarchy  into  an  instance  of  its  own  class.  If  the  argument  is 
higher  in  the  type  hierarchy,  or  is  incomparable  with  its  own  class,  the  convert()  method  throws  an 
exception.  If  the  argument  to  convert()  already  has  the  correct  type,  it  is  returned  without  any  change. 
Many  of  the  simpler  token  classes  also  provide  a  static  convert()  method  that  can  be  used  more  simply 
than  the  convert()  method  of  the  corresponding  type. 

Most  implementations  of  the  add(),  subtract(),  multiply(),  divide(),  modulo(),  and  equals()  meth¬ 
ods  require  that  the  type  of  the  argument  and  the  implementing  class  be  comparable  in  the  type  hierar¬ 
chy.  If  this  condition  is  not  met,  these  methods  will  throw  an  exception.  If  the  type  of  the  argument  is 
lower  than  the  type  of  the  implementing  class,  then  the  argument  is  usually  converted  to  the  type  of  the 
implementing  class  before  the  operation  is  carried  out.  One  exception  is  the  implementation  of  these 
methods  for  matrix  tokens.  To  allow  matrices  to  be  multiplied  and  divided  by  scalars,  the  normal  con¬ 
version  is  not  performed.  The  MatrixToken  base  class  deals  specially  with  scalar-matrix  operations. 

To  allow  this,  the  implementation  of  most  operations  is  somewhat  more  complicated  if  the  type  of 
the  method  argument  is  higher  than  the  implementing  class.  In  this  case,  we  assume  the  operation  is 
implemented  in  the  class  that  has  the  higher  type  (the  matrix  token  in  the  above  example).  Since  token 
operations  need  not  be  commutative,  for  example,  "Hello"  +  "world"  is  not  the  same  as  "world" 
+  "Hello",  and  3-2  is  not  the  same  as  2-3,  the  implementation  of  arithmetic  operations  cannot  simply 
call  the  same  method  on  the  class  of  the  argument.  Instead,  a  separate  set  of  methods  is  provided, 
which  perform  token  operations  in  the  reverse  order.  These  methods  are  addReverse(),  subtractRe- 
verse(),  multiplyReverse(),  divideReverse(),  and  moduloReverse().  The  equality  check  is  always  com¬ 
mutative  so  no  equalsReverse()  is  needed.  Under  this  setup,  a.add(b)  means  a+b,  and  a.addReverse(b) 
means  b+a,  where  a  and  b  are  both  tokens.  If,  for  example,  when  a.add(b)  is  invoked  and  the  type  of  b 
is  higher  than  a,  the  add()  method  of  a  will  automatically  call  b.addReverse(a)  to  carry  out  the  addi¬ 
tion. 

For  scalar  and  matrix  tokens,  methods  are  also  provided  to  convert  the  content  of  the  token  into 
another  numeric  type.  In  the  ScalarToken  base  class,  these  methods  are  intValue(),  longValue(),  dou¬ 
ble  Value(),  fixValue(),  and  complex Value().  In  the  MatrixToken  base  class,  the  methods  are  intMa- 
trix(),  longMatrix(),  doubleMatrix(),  fixMatrix(),  and  complexMatrix().  The  default  implementation  in 
these  two  base  classes  simply  throws  an  exception.  Derived  classes  override  these  methods  according 
to  the  automatic  type  conversion  relation  of  the  type  lattice.  For  example,  the  IntToken  class  overrides 
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all  the  methods  defined  in  ScalarToken,  but  the  DoubleToken  class  does  not  override  the  intValue() 
method,  since  automatic  conversion  is  not  allowed  from  a  double  to  an  integer. 

3.5  Variables  and  Parameters 

In  Ptolemy  II,  any  instance  of  NamedObj  can  have  attributes,  which  are  instances  of  the  Attribute 
class.  A  variable  is  an  attribute  that  contains  a  token.  Its  value  can  be  specified  by  an  expression  that 
can  refer  to  other  variables.  A  parameter,  implemented  by  the  Parameter  class,  is  in  most  ways  func¬ 
tionally  identical  to  a  variable,  but  also  appears  modifiable  from  the  user  interface.  See  figure  3.4  and 
figure  3.5.  The  presence  of  these  two  separate  classes  allows  variables  to  exist  which  are  internal  to  an 
actor,  and  not  visible  to  an  end  user.  For  the  rest  of  this  section  we  consider  parameters  and  variables  to 
be  largely  interchangeable. 

3.5.1  Values 

The  value  of  a  variable  can  be  specified  by  a  token  passed  to  a  constructor,  a  token  set  using  the 
setToken()  method,  or  an  expression  set  using  the  setExpression()  method. 

When  the  value  of  a  variable  is  set  by  setExpression(),  the  expression  is  not  actually  evaluated 
until  you  call  getToken()  or  getType().  This  is  important,  because  it  implies  that  a  set  of  interrelated 
expressions  can  be  specified  in  any  order.  Consider  for  example  the  sequence: 

Variable  v3  =  new  Variable (container, "v3" ) ; 

Variable  v2  =  new  Variable (container, "v2" )  ; 

Variable  vl  =  new  Variable (container,  "vl ") ; 
v3  .  setExpression ( "vl  +  v2"); 
v2 . setExpression ("1.0")  ; 
vl . setExpression  ("2.0")  ; 
v3 . getToken ( ) ; 

Notice  that  the  expression  for  v3  cannot  be  evaluated  when  it  is  set  because  v2  and  vl  do  not  yet  have 
values.  But  there  is  no  problem  because  the  expression  is  not  evaluated  until  getToken()  is  called. 
Obviously,  an  expression  can  only  reference  variables  that  are  added  to  the  scope  of  this  variable 
before  the  expression  is  evaluated  (i.e.,  before  getToken()  is  called).  Otherwise,  getToken()  will  throw 
an  exception.  By  default,  all  variables  contained  by  the  same  container  or  any  container  above  in  the 
hierarchy  are  in  the  scope  of  this  variable.  Thus,  in  the  example  above,  all  three  variables  are  in  each 
other's  scope  because  they  belong  to  the  same  container.  This  is  why  the  expression  "vl  +  v2 "  can  be 
evaluated.  If  two  containers  above  in  the  hierarchy  contain  the  same  variable,  then  the  one  lowest  in 
the  hierarchy  will  shadow  the  one  that  is  higher.  That  is,  the  lower  one  will  be  used  to  evaluate  the 
expression. 

3.5.2  Types 

Ptolemy  II,  in  contrast  to  Ptolemy  Classic,  does  not  have  a  plethora  of  type-specific  parameter 
classes.  Instead,  a  parameter  has  a  type  that  reflects  the  token  it  contains.  The  allowable  types  of  a 
parameter  or  variable  can  also  be  constrained  using  the  following  mechanisms: 

•  You  can  require  the  variable  to  have  a  specific  type.  Use  the  setTypeEqualsQ  method. 
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i  «lnterface»  | 

Attribute 

■ptolemy.  kernel.  util.ValueListener'i 

i+valueChanged(settable  :  Settable)! 

‘ 


«lnterface» 

ptolemy.data.type.  Typeable 


:  +getType() :  Type 
\+getTypeTerm()  :  InequalityTerm 
i+isTypeAcceptable() :  boolean 
\+setTypeAtLeast(lesser :  Typeable) 
\+setTypeAtLeast(typeTerm :  InequalityTerm) 
\+setTypeAtMost(type :  Type) 
\+setTypeEquals(type  :  Type) 
\+setTypeSameAs(equal :  Typeable) 
\+typeConstraintList() :  List 

r  5 


:  « Interface* 

;  ptolemy. kernel. util. Settable 

j+EXPERT  :  Settable.Visibiiitv 
l+FULL  :  Settable. Visibility 
l+NONE  :  Settable.Visibiiitv 
i+addValueListener(l  :  ValueListener) 
i+getExpression() :  String 
j+getVisibility()  :  Settable. Visibility 
i+removeValueListener(l  :  ValueListener) 
i+setExpression(expression  :  String) 
l+setVisibility(visibility  :  Settable. Visibility) 
i+validate() 

. A 


Variable 


-_currentExpression  :  String 
-_parser :  PtParser 
-_token  :  Token 
+Variable() 

+Variable(workspace  :  Workspace) 

+Variable(container :  NamedObj,  name  :  String) 
+Variable(container :  NamedObj,  name  :  String,  token  :  Token) 
+addToScope(variables  :  Enumeration) 

+addToScope(var :  Variable) 

+getScope()  :  List 
+getToken()  :  Token 
+isKnown() :  boolean 
+isLazy()  :  boolean 
+propagate() 

+removeFromScope(variables  :  Enumeration) 
+removeFromScope(var :  Variable) 

+reset() 

+setLazy(lazy  :  boolean) 

+setToken(token  :  Token) 

+setUnknown(unknown  :  boolean) 

+validate() 

#_addScopeDependent(var :  Variable) 
#_addValueDependent(Variable  :  var) 

#_isLegallnScope(var :  Variable) 

#_notifyValueListeners() 


uses  to  parse 

1..1  I  oAT 


contained 


0..1  1-1 


PtParser 


Token 


Parameter 


+Parameter() 

+Parameter(workspace  :  Workspace) 

+Parameter(container :  NamedObj,  name  :  String) 
+Parameter(container :  NamedObj,  name  :  String,  token  :  Token) 


FIGURE  3.4.  Static  structure  diagram  for  the  Variable  and  Parameter  classes  in  the  data.expr  package. 
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PtParser 


-  classesSearched  :  List 
+PtParser() 

+PtParser(stream  :  InputStream) 

+PtParser(tm  :  PtParserTokenManager) 

+PtParser(stream  :  Reader) 

+PtParser(owner :  Variable) 

+arrayConstruct() 

+bitwiseAnd() 

+bitwiseOr() 

+disable_tracing() 

+element() 

+enable_tracing() 

+funclf() 

+function() 

+generateParseException() :  ParseException 

+generateParseTree(expression  :  String) :  ASTPtRootNode 

+generateParseTree(stringln  :  String,  scope  :  NamedList) :  ASTPtRootNode 

+generateParseTree(stringln  :  String,  scope  :  ParserScope) :  ASTPtRootNode 

+getNextToken() :  Token 

+qetReqisteredClasses() :  List 

+getScope() :  NamedList 

+getToken(index  :  int) :  Token 

+getUndefinedList(expression  :  String) :  LinkedList 

+logicalAnd() 

+logicalEquals() 

+logicalOr() 

+matrixConstruct() 

+primaryElement() 

+recordConstruct() 

+reqisterConstant(name  :  String,  value  :  Object) 
+reqisterFunctionClass(newClassName  :  String) 

+Relnit(stream  :  InputStream) 

+Relnit(tm  :  PtParserTokenManager) 

+Relnit(stream  :  Reader) 

+relational() 

+start() :  ASTPtRootNode 
+sum() 

+term() 

+unary() 


Generated  from  PtParser.jjt 
using  JJTree  and  JavaCC 


Registered 

Classes 


#_children  :  ArrayList 
#_childTokens  :  TokenQ 
#_id  :  int 

#_isConstant :  boolean 
#_lexicalTokens  :  List 
#_parent :  Node 
#_parser :  PtParser 
#_ptToken  :  ptolemy.data.Token 


The  root  node  is  the  root  of  the  parse 
tree,  and  is  also  the  base  class  for  all 
other  node  types. 


+ASTPtRootNode(p  :  PtParser,  i :  int) 
+ASTPtRootNode(i :  int) 
+displayParseTree(prefix :  String) 
+evaluateParseTree() :  ptolemy.data.Token 
#_resolveNode() :  ptolemy.data.Token 


«lnterface» 

Node 


+jjtAddChild(child :  Node,  index :  int)  \ 
+jjtClose() 

+jjtGetChild(index :  int) :  Node 
+jjtGetNumChildren()  :  int 
+jjtGetParent() :  Node 
+jjtOpen() 

+jjtSetParent(parent :  Node) 


Generated  by 
JavaCC 


Constants 

ConcreteMatrixToken 

ConcreteScalarToken 

FIGURE  3.5.  Static  structure  diagram  for  the  parser  classes  in  the  data.expr  package 
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•  You  can  require  the  type  to  be  at  most  some  particular  type  in  the  type  hierarchy  (see  the  Type 
System  chapter  to  see  what  this  means). 

•  You  can  constrain  the  type  to  be  the  same  as  that  of  some  other  object  that  implements  the  Type- 
able  interface. 

•  You  can  constrain  the  type  to  be  at  least  that  of  some  other  object  that  implements  the  Typeable 
interface. 

Except  for  the  first  type  constraint,  these  are  not  checked  by  the  Variable  class.  They  must  be  checked 
by  a  type  resolution  algorithm,  which  is  executed  before  the  model  runs  and  after  parameter  values 
change. 

The  type  of  the  variable  can  be  specified  in  a  number  of  ways,  all  of  which  require  the  type  to  be 
consistent  with  the  specified  constraints  (or  an  exception  will  be  thrown): 

•  It  can  be  set  directly  by  a  call  to  setTypeEquals().  If  this  call  occurs  after  the  variable  has  a  value, 
then  the  specified  type  must  be  compatible  with  the  value.  Otherwise,  an  exception  will  be  thrown. 
Type  resolution  will  not  change  the  type  set  through  setTypeEquals()  unless  the  argument  of  that 
call  is  null.  If  this  method  is  not  called,  or  called  with  a  null  argument,  type  resolution  will  resolve 
the  variable  type  according  to  all  the  type  constraints.  Note  that  when  calling  setTypeEquals()  with 
a  non-null  argument  while  the  variable  already  contains  a  non-null  token,  the  argument  must  be  a 
type  no  less  than  the  type  of  the  contained  token.  To  set  type  of  the  variable  lower  than  the  type  of 
the  currently  contained  token,  setToken()  must  be  called  with  a  null  argument  before  setType- 
Equals(). 

•  Setting  the  value  of  the  variable  to  a  non-null  token  constrains  the  variable  type  to  be  no  less  than 
the  type  of  the  token.  This  constraint  will  be  used  in  type  resolution,  together  with  other  con¬ 
straints. 

•  The  type  is  also  constrained  when  an  expression  is  evaluated.  The  variable  type  must  be  no  less 
than  the  type  of  the  token  the  expression  is  evaluated  to. 

•  If  the  variable  does  not  yet  have  a  value,  then  the  type  of  a  variable  may  be  determined  by  type  res¬ 
olution.  In  this  case,  a  set  of  type  constraints  is  derived  from  the  expression  of  the  variable  (which 
presumably  has  not  yet  been  evaluated,  or  the  type  would  be  already  determined).  Additional  type 
constraints  can  be  added  by  calls  to  the  setTypeAtLeast()  and  setTypeSameAs()  methods. 

Subject  to  specified  constraints,  the  type  of  a  variable  can  be  changed  at  any  time.  Some  of  the  type 
constraints,  however,  are  not  verified  until  type  resolution  is  done.  If  type  resolution  is  not  done,  then 
these  constraints  are  not  enforced.  Type  resolution  is  normally  done  by  the  Manager  that  executes  a 
model. 

The  type  of  the  variable  may  change  when  setToken()  or  setExpression()  is  called. 

•  If  no  expression,  token,  or  type  has  been  specified  for  the  variable,  then  the  type  becomes  that  of 
the  current  value  being  set. 

•  If  the  variable  already  has  a  type,  and  the  value  can  be  converted  losslessly  into  a  token  of  that 
type,  then  the  type  is  left  unchanged. 

•  If  the  variable  already  has  a  type,  and  the  value  cannot  be  converted  losslessly  into  a  token  of  that 
type,  then  the  type  is  changed  to  that  of  the  current  value  being  set. 

If  the  type  of  a  variable  is  changed  after  having  once  been  set,  the  container  is  notified  of  this  by  call¬ 
ing  its  attributeTypeChanged()  method.  If  the  container  does  not  allow  type  changes,  it  should  throw 
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an  exception  in  this  method.  If  the  value  is  changed  after  having  once  been  set,  then  the  container  is 
notified  of  this  by  calling  its  attributeChanged()  method.  If  the  new  value  is  unacceptable  to  the  con¬ 
tainer,  it  should  throw  an  exception.  The  old  value  will  be  restored. 

The  token  returned  by  getToken()  is  always  of  the  type  given  by  the  getType()  method.  This  is  not 
necessarily  the  same  as  the  type  of  the  token  that  was  inserted  via  setToken().  It  might  be  a  distinct 
type  if  the  contained  token  can  be  converted  losslessly  into  one  of  the  type  given  by  getType().  In  rare 
circumstances,  you  may  need  to  directly  access  the  contained  token  without  any  conversion  occurring. 
To  do  this,  use  getContainedToken(). 

3.5.3  Dependencies 

Expressions  set  by  setExpression()  can  reference  any  other  variable  that  is  within  scope.  By 
default,  the  scope  includes  all  variables  contained  by  the  same  container  or  any  container  above  it  in 
the  hierarchy.  In  addition,  any  variable  can  be  explicitly  added  to  the  scope  of  a  variable  by  calling 
addToScopeQ. 

When  an  expression  for  one  variable  refers  to  another  variable,  then  the  value  of  the  first  variable 
obviously  depends  on  the  value  of  the  second.  If  the  value  of  the  second  is  modified,  then  it  is  impor¬ 
tant  that  the  value  of  the  first  reflects  the  change.  This  dependency  is  automatically  handled.  When  you 
call  getToken(),  the  expression  will  be  reevaluated  if  any  of  the  referenced  variables  have  changed  val¬ 
ues  since  the  last  evaluation. 

3.6  Expressions 

Ptolemy  II  includes  a  extensible  expression  language.  This  language  permits  operations  on  tokens 
to  be  specified  in  a  scripting  fashion,  without  requiring  compilation  of  Java  code.  The  language  was 
designed  to  be  extremely  succinct,  using  overloaded  operators  instead  of  verbose  references  to  meth¬ 
ods  in  the  token  classes.1  The  expression  language  can  be  used  to  define  parameters  in  terms  of  other 
parameters,  for  example.  It  is  also  used  to  provide  end-users  with  the  ability  to  describe  simple  state¬ 
less  actors  without  resorting  to  writing  Java  code  through  the  Expression  actor.  The  expression  lan¬ 
guage  is  also  used  to  give  guards  and  resets  for  finite  state  machines  in  an  intuitive  fashion.  The  use  of 
the  expression  language  is  described  in  volume  1 . 

The  expression  language  is  extensible.  The  extension  mechanism  is  based  on  the  reflection  pack¬ 
age  in  Java  used  to  add  primitive  functions  and  constants  to  the  expression  language.  The  expression 
language  is  also  purely  functional,  meaning  that  it  lacks  sequencing  constructs  and  side  effects.  Build¬ 
ing  state  and  sequencing  into  models  is  done  through  the  use  of  models  of  computation,  allowing  a 
much  richer  set  of  concurrent  control  structures  than  is  possible  with  traditional  imperative  languages. 
The  language  is  higher-order,  since  it  is  integrated  with  the  the  FunctionToken  class.  This  allows  for 
new  functions  to  be  easily  declared  as  part  of  a  model,  using  expressions  and  for  these  expressions  to 
be  manipulated  and  passed  through  a  model  as  data.  Because  the  expression  language  is  side-effect 
free  this  mechanism  does  not  interact  in  unexpected  ways  with  concurrent  models  of  computation. 


1 .  The  Ptolemy  II  expression  language  uses  operator  overloading,  unlike  Java.  Although  we  fully  agree  that  the 
designers  of  Java  made  a  good  decision  in  omitting  operator  overloading,  our  expression  language  is  used  in  sit¬ 
uations  where  compactness  of  expressions  is  extremely  important.  Expressions  often  appear  in  crowded  dialog 
boxes  in  the  user  interface,  so  we  cannot  afford  the  luxury  of  replacing  operators  with  method  calls.  It  is  more 
compact  to  say  “2*(PI  +  2i)”  rather  than  “2.multiply(PI.add(2i)),”  although  both  will  work  in  the  expression  lan¬ 
guage. 
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Lastly,  the  expression  language  is  strongly  typed,  allowing  transparent  integration  with  the  static  type 
checking  of  components  specified  using  expression.  When  combined  with  the  higher-order  constructs 
the  resulting  language  has  the  feel  of  typed  lambda  calculus. 
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3.7  Unit  System 


The  unit  system  in  Ptolemy  II  is  based  on  the  paper  “Automatic  Units  Tracking”  by  Christopher 
Rettig  [132].  The  basic  idea  is  to  define  a  suite  of  parameters  to  represent  the  various  measurement 
units  of  a  unit  system,  such  as  “meter,”  “cm,”  “feet,”  “miles,”  “seconds,”  “hours,”  and  “days.”  In  each 
unit  category  (“length”  or  “time”  for  example),  there  is  a  base  unit  with  respect  to  which  all  the  others 
are  specified.  If  the  base  unit  of  length  is  meters,  then  “cm”  (centimeter)  will  be  specified  as 
“0.01  *  meters”.  Derived  units  are  specified  by  just  multiplying  and  dividing  base  units.  For  example 
“newton”  is  specified  as  “meter  *  kilogram  /  secondA2”. 

The  unit  parameters  contain  tokens  just  like  other  parameters.  To  track  units,  the  category  informa¬ 
tion  is  stored  together  with  measurement  data  in  scalar  tokens,  and  is  used  when  arithmetic  operations, 
such  as  add()  and  multiply(),  are  performed.  The  subclasses  of  ScalarToken,  including  IntToken  and 
DoubleToken,  override  these  methods  to  perform  unit  checking. 


The  ptolemy.data.unit  package  provides  three  classes  (BaseUnit,  UnitCategory,  and  UnitSystem) 
that  allow  a  unit  system  to  be  specified  using  MoML,  as  illustrated  in  figure  3.6.  When  such  a  unit  sys¬ 
tem  is  added  to  the  model  shown  in  figure  3.7,  the  units  can  be  used  in  expressions  to  specify  the  value 
of  actor  parameters.  The  displayed  result  of  executing  the  model  is  “10.0  *  m  /  s”. 

Several  basic  unit  systems  are  provided  with  Ptolemy  II.  In  the  Vergil  graph  editor,  they  appear  in 
the  utilities  library.  A  unit  system  added  to  a  composite  actor  can  only  be  used  inside  that  actor.  The 


<property  name="Sample"  class="ptolemy . data. unit . UnitSystem"> 

<property  name="m"  class="ptolemy . data . unit . BaseUnit"  value="1.0"> 
<property  name="Length"  class="ptolemy . data . unit . UnitCategory"/> 
</property> 

<property  name="cm"  class="ptolemy . data . expr . Parameter"  value="0 . 01*m"/> 
<property  name="s"  class="ptolemy . data . unit . BaseUnit"  value="1.0"> 
<property  name="Time"  class="ptolemy . data . unit . UnitCategory" /> 
</property> 

<property  name="ms"  class="ptolemy. data . expr . Parameter"  value="0 . 001*s"/> 
</property> 


FIGURE  3.6.  A  sample  unit  system. 


Sample  SDF  Director 


FIGURE  3.7.  A  model  that  uses  the  sample  unit  system. 
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user  can  customize  a  unit  system  by  adding  units,  or  create  new  unit  systems  based  on  those  provided. 
The  current  implementation  of  unit  systems  has  the  following  limitations: 

•  Only  scalar  values  can  have  units. 

•  The  result  of  calling  a  function  on  a  value  with  units  is  unit-less. 


3.8  The  Static  Unit  System 


This  section  presents  the  static  units  system  in  Ptolemy.  In  contrast  to  the  unit  system  in  the  previ¬ 
ous  section,  which  is  dynamic,  the  purpose  of  the  static  unit  system  is  to  analyze  a  model  before  it  is 
run.  In  particular,  the  static  units  system  is  used  to  analyze  the  structure  of  the  model  and  determine  if 
it  is  correct  in  terms  of  the  units  of  measure. 


In  the  dynamic  unit  systems  units  of  measure  is  an  integral  part  of  a  data  value,  i.e.  it  is  encapsu¬ 
lated  as  part  of  the  data  Token.  In  contrast,  in  the  static  unit  system  information  about  units  of  measure 
is  in  the  form  of  specifications  attached  to  ports.  This  information  can  be  interpreted  as  a  implying  that 
any  data  Token  that  passes  through  the  port  at  run-time  will  have  those  unit  specifications.  That  is,  it  is 
a  constraint  that  must  be  met  when  the  model  is  run.  If  the  static  unit  system  can  determine  that  con¬ 
straints  of  a  model  will  be  met  at  run-time  then  the  model  is  said  to  be  units  consistent. 


As  an  example,  consider  part  of  the  model  that  is  used  in  the  StaticUnits  demonstration  and  is 


work. 


HeatProduckon  $heat  =  calories 
D]_|-|  ^tlSfll - $heat  =  $plus 


AddSubtract 


0  + 


The  HeatProduckon.heat  port  has  units 
calones,  but  the  HeatExchanger.output 
has  units  calones/second.  The 
AddSubtract  actor  requires  that  the  units  on 
the  plus,  and  minus  ports  be  the  same. 
Therefore,  the  units  constraints  in  this 
part  of  the  model  are  inconsistent. 


_ $minus  =  $plus 

$output  =  $minus 


$output  =  gallonUS 
flow 

[{i  100  if  $°utput  =  Sflow  •  I 

The  flow.output  port  has 
units  gallonUS  while  the 
HeatExchanger.flow  port 
has  units  gallonUS/hour. 


HeatExchanger 


$f 


Eoutput  =  calories/sec 


ow  =  gallonUS/hour 


FIGURE  3.8.  Part  of  the  StaticUnits  demonstration.  The  colored  boxes  indicate 
the  unit  constraints  in  this  part  of  the  model. 


shown  in  Figure  3.8.  There  are  several  unit  constraints  shown  here.  Each  constraint  is  in  the  form  of  an 
equation  where  variables  begin  with  a  “$”  and  refer  to  ports  in  the  model.  The  constraints  with  green 
background  specify  that  a  port  will  pass  data  with  specific  units.  For  example,  the  equation  “$heat  = 
calories”  next  to  the  HeatProduction  actor  indicates  that  any  data  passing  through  the  heat  port  will  be 
in  units  of  calories.  The  constraints  with  cyan  background  specifies  the  relationship  among  ports  on  a 
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particular  actor.  In  this  case  the  AddSubtract  actor  requires  that  the  plus,  minus,  and  out  ports  all  have 
the  same  units  without  specifying  what  those  units  will  be.  The  constraints  with  the  yellow  background 
exist  when  ports  on  different  actors  are  connected  via  a  relation. 

It  can  be  seen  that  equations  of  the  model  in  Figure  3.8  are  inconsistent.  For  example,  the  equa¬ 
tions 

$output  =  gallonUS 
$output  =  $flow 
$flow  =  gallonUS/hour 

can  not  all  be  true. 

In  a  real  sense,  static  unit  specifications  are  an  extension  of  conventional  data  types.  For  example, 
a  datum  may  be  of  type  double,  but,  in  addition,  also  be  known  to  represent  calories/sec.  It  is  tempting 
to  extend  the  analytic  techniques  applicable  for  conventional  data  types  to  the  realm  of  units  of  mea¬ 
sure.  However,  conventional  data  types  analytic  techniques  do  not  appear  to  be  effective  in  dealing 
with  static  unit  specifications.  Lattices  defined  on  data  type  inequalities  is  the  basis  for  powerful  tech¬ 
niques  for  analyzing  data  types.  Although  type  lattices  can  be  defined  for  units  specifications  they 
seem  trivial,  and  have  not  lead  to  any  useful  techniques.  In  contrast,  the  relationship  amongst  the  units 
specifications  of  a  model  are  best  characterized  with  a  set  of  equations.  This  approach  is  the  basis  for 
determining  if  a  model  is  units  consistent. 

A  strategic  goal  in  the  design  and  implementation  was,  both,  to  leave  the  dynamic  unit  capability 
intact,  and  to  re-use  the  dynamic  unit  components  where  possible. 

3.8.1  Unit  Systems 

A  unit  system  is  based  on  1)  an  ordered  set  {Dx,D2...,Dn}  where  each  {  Di }  represents  a  dimen¬ 
sion,  and  2)  a  base  unit  for  each  dimension.  The  intent  is  that  each  dimension  is  orthogonal  to  all  other 
dimensions,  and  that  any  unit  of  measure  can  be  expressed  as  a  combination  of  the  base  units.  An 
example  of  a  unit  system  in  widespread  use  is  the  International  System  of  Units  shown  in  Table  10 


Index 

Dimension 

Base  Unit 

1 

Length 

Meter 

2 

Time 

Second 

3 

Temperature 

Kelvin 

4 

Mass 

Kilogram 

5 

Current 

Ampere 

6 

Substance 

Mole 

7 

Luminosity 

Candela 

Table  10:  System  International  Unit  System 


In  order  to  simplify  the  presentation  of  examples  in  this  section  the  Simple  unit  system  shown  in 


Index 

Dimension 

Base  Unit 

1 

Length 

Meter 

Table  11:  Simple  Unit  System 
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Index 

Dimension 

Base  Unit 

2 

Time 

Second 

3 

Mass 

Kilogram 

Table  11:  Simple  Unit  System 


Table  1 1  will  be  used  throughout. 

3.8.2  Units  of  Measurement  Algebra 

The  type  of  a  unit  is  expressed  as  (e  lv..,  en)  where  each  el  represents  the  exponent  of  the  corre¬ 
sponding  dimension.  For  example,  ( 1,  -1,  0)  (i.e.  Length/Time)  is  a  type  in  the  Simple  unit  system, 
and  is  commonly  referred  to  as  speed.  The  set  of  types  for  a  unit  system  are  a  set  of  points  in  N-dimen- 
sional  space.  For  example,  a  unit  system  with  just  the  categories  Length  and  Time  (i.e.  without  Mass) 
would  look  like 


Length 


Time 


A  type  is  said  to  be  singular  if  it  has  the  property  that  just  one  of  the  exponents  is  1  and  the  rest  are 
0.  The  type  (0,  . . .,  0)  is  said  to  be  the  unitless  type. 

A  unit  is  obtained  by  combining  a  scale  with  a  type.  A  unit  U  is  expressed  as 

U  =  a(el,...,en)  where  a  e  Reals  (1) 

where  a  is  the  scale  of  U.  Please  note  that  (1)  does  not  imply  the  multiplication  of  (el,...,en)  by  a.  In 
particular,  a(el,...,en)  ^  (ael,...,aen)  A  unit  is  said  to  be  singular  if  its  type  is  singular.  A  unit  is 
said  to  be  basic  if  a  =  1.0. 
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Refer  to  Table  12  for  some  examples  of  units. 


Unit 

Descriptive 

Form(s) 

Scale 

Type 

Properties 

1.0<1,0,  0> 

Meter,  m 

1.0 

<1,  o,  0> 

basic,  singular 

1.0<0,  1,  0> 

Sec,  s 

1.0 

o,  1,0> 

basic,  singular 

1.00,  0,  1> 

Kilogram,  kg 

1.0 

o,  0,  1> 

basic,  singular 

0.0K1,  0,  0> 

Centimeter,  cm 

0.01 

<1,0, 0> 

singular 

36000,  1,  0> 

Hour,  hr 

3600 

<0, 1,  o> 

singular 

0.4535920,  0,  1> 

Pound,  lb 

0.453592 

<0,  0,  1> 

singular 

1.0<1,-1,0> 

meters/sec,  m/s 

1.0 

<1,-1,  0> 

basic 

0.44704<1,  -1,  0> 

miles/hour,  mph 

0.44704 

<1,-1,  0> 

9.80665<1,  -2,  0> 

g  (gravity) 

9.80665 

<1,-2,  0> 

3.141580,  0,  0> 

pi,  TC 

3.14159 

O,  0,  0> 

unitless 

Table  12:  Examples  of  Units 


The  unit  multiplication  of  two  units  is  the  vector  addition  of  the  two  types  and  the  “normal”  multi¬ 


plication  of  the  two  scales.  That  is 

U\  x  U2  =  ax*a2(exx  +  eX2,e2X  +  e22...enX  +  en,i>  where 


Ul  ax{elx,e2X,...,enX) 
U2  =  a2{e x  2,e2  2,. . .  Xn  f) 


Unit  exponentiation  follows  from  multiplication,  i.e. 

if  =  ax  (xeXrxe2,...rxen) 

The  notion  of  a  unit  variable  is  assumed  and  has  the  properties  commonly  found  in  computational 
systems.  A  unit  expression  has  the  form 

p  p  r  U  is  a  unit  t 

U  x  Xx  1  x  ...  x  Xq  q  where  \  P .  > 

\Xl  '  is  the  variable  X-  raised  to  the  Pt  power J 


A  unit  equation  has  the  form 


p  P  s,  s.  f  each  X-,Y-  is  a  variable  1 

UyxX,  x  . . .  x  Xn  q  =  UY  x  T,  x  ...  x  Yr  '  where  \  > 

q  [  Ux  and  UY  are  Units  J 


(2) 


An  equation  is  said  to  be  in  canonical  form  if  the  left  side  consists  solely  of  powers  of  variables 
and  the  right  side  is  a  unit,  i.e. 

P  P 

t/1  t /N  t  t 

Vx  X  ...  X  VN  =  U 

Any  equation  in  the  form  of  (2)  can  be  translated  to  an  equivalent  canonical  form  by  first  multiply¬ 
ing  both  sides  of  (2)  by  uj  x  Yx  1  x  . . .  x  Yr  '  yielding 
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P ,  P„  -S,  -S,.  _i 

Xj1  X  ...  xl?!  X  7j  1  X  ...  X  7r  =  UYX  ux  (3) 

The  right  side  of  (3)  can  be  further  reduced  since  UY  and  U x  are  both  units,  i.e.  they  are  not  variables. 
If  U  is  the  value  of  the  expression  UY  x  Ux  then  (3)  can  be  rewritten  as 

p,  p„  -s,  -S 

Xx  x  ...  xXgqx  7j  1  x  ...  x  7r  =U  (4) 

which  has  just  powers  of  variables  on  the  left  side  and  a  unit  on  the  right  side. 

3.8.3  Descriptive  Form  Language 

The  descriptive  form  of  a  unit  is  a  natural  language  string  that  humans  normally  use  when  referring 
to  a  unit  of  measure.  Table  12,  above,  shows  some  examples  of  descriptive  forms.  In  the  Static  Unit 
System  descriptive  forms  are  realized  through  a  formal  language,  called  Descriptive  Form  Language, 
and  its  associated  grammar  shown  in  Figure  3.9 

Root  ::=  UnitEquation  |  UnitExpression 
UnitEquation  ::=  UnitExpr  "="  UnitExpr 

UnitExpr  ::=  UnitTerm  {"/"  UnitTerm  |  UnitTerm  |  UnitTerm}* 

UnitTerm  ::=  UnitElement 

lUnitElement  "A"  <Number> 

| <Number> 

l"("  UnitExpr  ")" 

UnitElement  ::=  Unit|  Variable 
Variable  ::=  "$"  <String> 

FIGURE  3.9.  BNF  for  Descriptive  Fonn  Language 

For  example,  the  parse  tree  for  the  expression  “gallons/second”  is  shown  in  figure  3.10 


FIGURE  3.10.  Parse  Tree  for  “gallons/sec” 

The  Static  Unit  System  parser,  called  UParser,  is  generated  using  JavaCC  which  is  used  to  gener¬ 
ate  the  PtParser,  the  expression  parser  in  Ptolemy.  See  “Generating  the  parse  tree”  on  page  4-86.  One 
key  difference  is  that  the  generation  of  UParser  does  not  start  from  a  JJTree  specification.  Instead  the 
DFL  grammar  is  specified  in  the  UParser.jj  which  is  input  directly  to  JavaCC. 

If  it  were  possible  it  would  have  been  advantageous  to  make  DFL  a  subset  of  the  expression  lan¬ 
guage.  However,  there  are  two  differences  between  the  DFL  and  the  data  expression  language  that  pre¬ 
clude  this  possibility.  First,  multiplication  in  DFL  can  be  expressed  via  concatenation  of  the 
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multiplicands.  For  example,  moment  arm  can  be  expressed  as  “foot  pound”  in  DFL.  There  is  no  rule  in 
the  data  expression  grammar  that  provides  for  this  construction.  DFL  could  be  modified  so  that  multi¬ 
plication  requires  a  operator,  as  in  “foot*pound”(in  fact,  as  a  convenience,  DFL  accepts  this  con¬ 
struction).  However,  the  form  “foot  pound”  has  been  in  use  for  decades  and  it  was  judged  that  casual 
users  of  Ptolemy  would  find  the  requirement  of  the  operator  to  be  awkward. 

The  second  difference  stems  from  the  necessity  to  have  variables  distinquishable  from  unit  labels. 
The  data  expression  language  does  not  have  a  way  to  explicitly  distinguish  variables,  as  it  is  clear  from 
the  context.  The  example  presented  in  Figure  3.8  shows  the  descriptive  form  “$heat  =  calories” 
expressing  the  constraint  that  the  port  with  name  heat  has  unit  calories.  Without  the  “$”  to  distinguish 
heat  as  a  port  name  the  parser  would  try  to  interpret  heat  as  a  unit. 

3.8.4  Implementing  the  Static  Unit  System  in  Ptolemy 

This  subsection  presents  the  internal  form  that  is  implemented  as  a  set  of  classes  in  Ptolemy.  Fig¬ 
ure  3.11  presents  the  UML  static  structure  for  these  classes. 
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UnitConstraint 


+descriptiveForm() :  String 
+getLhs() :  UnitExpr 
+getOperator() :  String 
+getRhs() :  UnitExpr 
+getSource() :  NamedObj 
+setLhs(expr :  UnitExpr) 
+setRhs(expr :  UnitExpr) 
+setSource(source :  NamedObj) 
+toString() :  String 
- A - — TT - 


«lnterface» 

UnitPresentation 

+descriptiveForm() :  String 
+toString() :  String 

A  7 


UnitEq 

luation 

+areSatisfied(equations  :  Vector,  bindinqs  :  Bindings) :  boolean 

+canonicalize() 

+copy() :  UnitEquation 
+isSatisfied(bindings  :  Bindings 
+visitor(visitor :  EquationVisitor) 

) :  boolean 
:  Object 

«Future» 

UnitlnEquality 


0..1 


0..1 


Unit 


-Jabels  :  Vector 
-_scale :  double 
-_type :  intQ 
+copy() :  Unit 
+descriptiveForm() :  String 
+divideBy(divisor :  Unit) :  Unit 
+factor() :  UnitExpr 
+equals(otherUnit :  Unit) :  boolean 
+getLabels() :  Vector 
+getLabelsString() :  String 
+getPrimaryl_abel() :  String 
+getScale() :  double 
+getType() :  intQ 

+hasSameType(otherUnit :  Unit) :  boolean 
+invert() :  Unit 

+multiplyBy(multiplicand  :  Unit) :  Unit 
+pow(power :  double) :  Unit 
+setPrimaryl_abel(label :  String) 
+setScale(scale :  double) 

+setType(type :  intQ) 

+toString() :  STRING 
#_setLabels(labels  :  Vector) 


UnitTerm 

UnitExpr 

-_exponent :  int 
-  type :  int 

- _ isFlat :  boolean 

--UTerms  :  Vector 

-  unit :  Unit 
-_unitExpr :  UnitExpr 
--Variable :  String 

+addUnit(unit :  Unit) 
+addUnitTerm(uTerm  :  UnitTerm) 
+copy() :  UnitExpr 

+copy() :  UnitTerm 
+descriptiveForm() :  String 
+getExponent() :  int 
+getType() :  intQ 
+getUnit() :  Unit 
+getUnitExpr() :  UnitExpr 

+descriptiveForm() :  String 
+getUTerms() :  Vector 
+invert() :  UnitExpr 
+reduce() 

+setUTerms(uTerms  :  Vector) 
+toString()() :  String 

+getVariable() :  String 

-_flatten() 

+invert() :  UnitTerm 
+isUnit() :  boolean 
+isUnitExpr() :  boolean 
+isVariable() :  boolean 

+multiplyBy(multiplicand  :  UnitTerm) :  UnitTerm 
+reduce() :  UnitTerm 
+setExponent(exponent :  int) 

+setType(type :  int) 

+setUnit(unit :  Unit) 

+setUnitExpr(expr :  UnitExpr) 

+setVariable(v :  String) 

+toString() 

+visit(visitor :  EquationVisitor) :  Object 

FIGURE  3.11.  Static  Structure  of  classes  used  ti  implement  units,  unit  expressions  and  unit  equations. 
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3.8.5  The  Unit  Library 

The  dynamic  units  system  is  architected  so  that  a  unit  system  is  associated  with  a  model.  Further, 
different  models  can  have  different  unit  systems.  In  contrast,  the  static  unit  systems  architecture  pro¬ 
vides  the  equivalent  functionality  with  a  UnitLibrary.  However,  there  is  one  common  UnitLibrary  in 
the  Ptolemy  system,  and  it  is  used  by  all  models  requiring  the  services  of  the  static  unit  system.  The 
UnitLibrary  is  loaded  the  first  time  Ptolemy  attempts  any  operations  that  will  require  the  UnitLibrary 
be  present. 

The  specifications  for  a  UnitLibrary  are  contained  in  a  file  with  the  exact  same  format  as  is  used  by 
the  dynamic  unit  system.  (Presently,  the  name  of  the  file  is  hardwired  to  be  ptolemy/data/unit/SI.xml.) 
When  loaded  by  the  static  unit  system  a  UnitSystem  appropriate  for  the  dynamic  unit  system  is  created 
as  a  side  effect.  It  is  the  subsequent  processing  of  this  UnitSystem  that  creates  the  UnitLibrary. 

Figures  3.12  and  3.13  show  parts  of  this  file 

<property  name="cm"  class="ptolemy . data . unit . BaseUnit"  value="1.0"> 
<property  name=" Length"  class="ptolemy . data . unit . UnitCategory"/> 
</property> 

<property  name="second"  class="ptolemy . data . unit . BaseUnit"  value="1.0"> 
<property  name="Time"  class="ptolemy . data . unit . UnitCategory" / > 
</property> 

FIGURE  3.12.  The  Length  and  Time  BasicUnits  specifications  from  the  Sl.xml  file 


<property  name=" light Speed"  class="ptolemy . data . expr . Parameter" 
value="2 997 92458 . 0*meter/ second" /> 

<property  name="gallonUS"  class="ptolemy . data . expr . Parameter" 
value="3785 . 412*cmA3"/> 

<property  name="pi"  class="ptolemy . data . expr . Parameter"  value="3 . 1415"/> 
<property  name="planckConstant"  class="ptolemy . data . expr . Parameter" 
value="hBar*2*pi"/> 

FIGURE  3.13.  The  lightSpeed  and  gallonUS  non-BasicUnit  specifications  from  the  Sl.xml  file. 

Although  the  file  format  is  identical  for  the  two  unit  systems  there  is  one  additional  requirement 
that  the  static  unit  system  imposes.  Non-BasicUnits  are  specified  as  a  Ptolemy  Parameter.  In  essence 
the  dynamic  unit  system  allows  external  references  to  units  outside  the  UnitSystem.  For  example,  the 
Parameter  pi  is  defined  elsewhere  in  the  Ptolemy  system  and  any  UnitSystem  can  refer  to  that  defini¬ 
tion.  In  contrast,  the  static  unit  system  is  based  on  an  architecture  where  the  UnitLibrary  is  self  con¬ 
tained.  This  is  necessary  in  order  to  distinguish  the  case  where  a  Parameter  is  not  a  unit.  Therefore,  for 
example,  pi  must  be  specified  in  the  file  as  shown  in  figure  3.13. 

3.8.6  Generating  Descriptive  Forms 

In  order  to  present  the  user  with  the  results  of  the  solver  it  is  necessary  to  generate  the  descriptive 
form  from  the  internal  representation  of  a  unit.  If  the  unit  exists  in  the  UnitLibrary  then  generation 
requires  only  that  the  descriptive  form  be  retrieved  from  the  UnitLibrary. 
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However,  it  is  often  the  case  that  the  unit  does  not  exist  in  the  UnitLibrary.  In  the  example  shown 
in  Figure  3.8  there  is  an  inconsistency  between  the  Flow.output  port  with  units  gallonUS  and  the 
HeatExchanger.flow  port  with  units  gallonUS/hour.  The  following  table  has  the  relevant  information 


Descriptive  Form 

Internal  Form 

Source 

1 

gallonUS 

3785.4120, 0,0> 

UnitLibrary 

2 

hour 

36000, 1,0> 

UnitLibrary 

3 

gallonUS  /  hour 

1.050, -1,0> 

derived  by  parsing  the  descriptive  form 

4 

to  be  generated 

.0002770,  -1,0> 

derived  by  solving  for  X  in  the  equation 

378.412(3,0,0}  x  X  =  1.05(3, -1,0) 

in  determining  the  descriptive  form  of  the  transformation  required  to  remove  this  inconsistency. 

The  internal  form  in  lines  1  and  2  are  values  obtained  from  the  UnitLibrary.  The  internal  form  in 
line  3  was  obtained  by  parsing  the  descriptive  form  “gallonUS/hour”  which  causes  the  calculation 
3785.412<3,0,0>  /  3600<0,10>  =  1.05<3,-1,0>  to  take  place.  The  internal  form  in  line  4  is  the  result  of 
solving  for  X  in  the  equation  378.412  (3,0,0}  x  X  =  1.05  (3,-1 ,0) .  That  is,  X  is  the  transformation  required 
to  remove  the  inconsistency  arising  from  the  sending  port  having  units  gallonUS  to  a  receiving  port 
having  units  gallonUS/hour.  In  order,  for  this  result  to  be  communicated  to  the  user  a  descriptive  form 
for  0. 0002770, -1,0>  must  be  generated.  By  noting  that  0. 0002770, -1,0>  =  1  /  36000, -1,0>  it  can  be 
determined  that  the  descriptive  form  for  0.0002770,- 1,0>  is  1/hour. 

Stated  formally,  generating  the  descriptive  form  for  a  unit  U  requires  that  U  be  factored  such  that 

/>!  PN 

U  =  Ul  x  ...  x  UN  where  each  U{  is  in  the  UnitLibrary.  In  theory,  the  complexity  of  this  factor¬ 
ization  is  infinite  since  the  range  of  each  Pf  is  infinite,  and  there  is  no  limit  on  the  size  of  N.  By  limit¬ 
ing  N  and  the  possible  values  of  Pt  the  complexity  can  be  made  at  least  finite.  In  the  current 
implementation  N  <2  and  Pt  e  {—2,— 1,1,2} .  If  a  factorization  does  not  exist  under  these  limitations 

the  descriptive  form  that  is  “generated”  is  just  a  string  representation  of  the  unit.  I.E.,  something  like 
“13.27E17<1,  -3,  2,  0>”.  In  practice,  this  seems  to  be  an  acceptable  limitation. 

3.8.7  UnitsConstraint  Solver 

The  purpose  of  the  solver  is  to  determine  if  the  unit  constraints  of  a  model  are  consistent.  It  does 
this  by  transforming  the  unit  constraints  to  a  set  of  unit  equations  in  canonical  form  and  then  perform¬ 
ing  a  modified  form  of  Gaussian  elimination. 

For  a  set  of  M  unit  equations  let  {  Vl,...,VN}  be  the  set  of  variables  that  occur  in  any  of  the  set  of 
unit  equations.  The  kth  unit  equation  can  then  be  transformed  to  its  canonical 

Pk  Pk 

form  V i  X  ...  X  VN  —  U^.  The  set  of  equations  in  canonical  form  is  represented  by  a  data 
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structure  called  a  powers  matrix  that  is  shown  in  Figure  3.14 


Vi 

•  •  • 

VN 

Pi,  1 

•  •  • 

P\,N 

Ui 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

P M,\ 

•  •  • 

Pm,n 

UM 

FIGURE  3.14.  Power  Matrix 


A  power  matrix  is  said  to  be  reducable  if  there  exists  a  row  k  that  has  all  but  one  of  the  Pk  ■  being 
0.  Eliminate  is  an  operator  that  can  be  applied  to  any  reducable  power  matrix.  The  result  of  the  elimi¬ 
nate  operator  is  another  power  matrix.  Let  Pk  l  be  that  element  not  equal  to  0,  then  the  resulting  power 

matrix  has  the  property  that  all  of  thc/J;  I  in  column  1  will  be  0  except  for  Pk  l  which  will  have  the 
value  1.  See  Figure  3.15 


V,  ...  vl 

...  VN 

vx  ... 

Vl 

...  vN 

P\,\  •••  P\,l 

•••  P\,N 

P\,l  ••• 

0 

Pl,N 

u\ 

•  • 

•  • 

• 

• 

• 

• 

Eliminate(k.l)  l 

• 

• 

• 

• 

• 

• 

•  • 

• 

• 

- — . 

• 

• 

• 

0  •  •  •  pk,l 

...  0 

Uk 

0  ... 

1 

...  0 

Uk 

•  • 

•  • 

• 

• 

• 

• 

• 

• 

• 

• 

•  • 

• 

• 

• 

• 

• 

• 

P M,\  •  •  •  P M,l 

PM,N 

U M 

• 

P M,\  *  *  * 

• 

0 

• 

•••  P  MJV 

• 

UM 

FIGURE  3.15.  The  eliminate  operation.  The  kth  row  must  have  all  0  except 
for  the  l1*1  column.  The  result  is  that  the  1th  column  will  be  all  zeros  except 

Pk J  =  1 

The  eliminate  operation  is  accomplished  in  two  steps.  The  first  step  replaces  Pk  t  with  1,  and  the 
second  step  replaces  all  of  the  other  Pt  in  the  1th  column  with  0.  To  accomplish  the  first  step  note 

that  the  kth  row  represents  the  equation  VkJ  =  Uk.  If  both  sides  of  this  equation  are  raised  to  the 

l  x/pki  l/pki 

1  /Pk  l  this  equation  becomes  Vk  =  Uk  ’  .  Thus,  Pk  l  has  been  replaced  with,  and  Uk  =  Uk 
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l  /  r  k  i 

The  second  step  requires  that  it  be  assumed  that  the  value  of  the  variable  Vt  is  in  fact  Uk  '  .  Any 

p,  p,  p, 

other  row  i  that  is  not  the  km  row  represents  the  im  equation  Vx  x  ...  x  x  ...  x  VN  =  Ui .  Multi- 

~pi, 

plying  both  sides  of  this  equation  by  Vt  yields 

V\l  x  ...  x  x  ...  x  V^N  =  UlVlP,‘ 

=  utu?,yPkJ 

-fa 

Thus,  Pt  /  has  been  replaced  with  0,  and  U/  =  UjUk  kJ 

A  power  matrix  is  said  to  be  inconsistent  if  there  exists  a  row  k  with  all  Pk-  =  0  but  Uk^  I .  Note 
that  if  a  power  matrix  M  is  inconsistent  then  no  elimination  on  M  can  yield  a  power  matrix  that  is  con¬ 
sistent.  A  power  matrix  is  said  to  be  ambiguous  if  there  exists  a  column  1  with  more  than  1  of  the 
Pj  i  not  equal  to  0.  A  power  matrix  that  is  consistent  and  non-ambiguous  yields  a  set  of  bindings  for  the 
variables,  a  power  matrix  is  said  to  be  unique  if  there  does  not  exist  any  column  1  where  all  of  the 
P i  j  are  0. 

Gaussian  elimination  is  the  repeated  application  of  the  eliminate  operation  that  terminates  when 
the  power  matrix  can  not  be  further  reduced.  The  final  non-reducable  power  matrix  is  then  used  to 
determine  the  status  of  the  original  set  of  unit  equations.  Let  Mr  be  the  power  matrix  that  resulting 
from  a  Gaussian  elimination.  If  Mr  is  inconsistent  or  ambiguous  then  the  set  of  unit  equations  does  not 
have  a  solution.  That  is,  there  is  no  set  of  bindings  for  the  variables  that  will  cause  all  of  the  unit  equa¬ 
tions  to  be  satisfied.  If  Mr  is  consistent  and  non-ambiguous  then  there  does  exist  a  set  of  bindings  for 
the  variables  that  will  cause  the  unit  equations  to  be  true.  Further,  if  Mr  is  unique  then  there  exist  a 
binding  set  that  includes  all  the  variables  that  will  cause  the  unit  equations  to  be  true.  Figure  3.16 
shows  examples  of  inconsistent  and  ambiguous  power  matrices. 


Vi  V2 

Vi  v2 

0  1 

calories 

1  0 

calories 

0  0 

calories/sec 

1  0 

calories/sec 

Inconsistent 

Ambiguous 

FIGURE  3.16.  Examples  of  inconsistent,  ambigu¬ 
ous  power  matrices 


Figure  3.17  shows  an  example  of  a  power  matrices  that  are  consistent,  and  non-ambiguous. 
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Vi 
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V3 
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1 
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calories 
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0 

calories/sec 

1 

0 

0 

calories/sec 
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0 

Identity 

0 

0 

0 

Identity 

FIGURE  3.17.  Consistent,  non-ambiguous  power  matrices.  The  binding  set  for  the  left  power 
matrix  is  {(V j,  calories),  (V2,  calories/sec.)}  The  binding  set  for  the  right  power  matrix  is {(V 1, 
calories),  (V2,  calories/sec.),  (V3,  <unbound>)} 


3.8.8  Minimal  Span  Solutions 

Usually  an  inconsistent  set  of  equations  can  be  made  consistent  by  modifying  one  or  more  of  the 
equations  and/or  changing  the  membership  of  the  set.  In  general,  however,  an  inconsistent  set  of  equa¬ 
tions  does  not  have  a  single  cause  for  the  inconsistency.  That  is,  it  is  the  set  of  equations  that  is  incon¬ 
sistent,  not  a  particular  equation  in  the  set  that  is  inconsistent.  Stated  another  way,  the  cause  of  the 
inconsistency  is  ambiguous.  As  a  result  the  algorithm  presented  in  the  previous  subsection  can  not  pro¬ 
vide  information  about  why  a  set  of  equations  is  inconsistent.  However,  it  may  be  possible  to  provide 
information  that  will  help  the  user  determine  which  modifications  are  appropriate.  This  is  done  by  pre¬ 
senting  the  user  with  a  set  of  minimal  span  solutions. 

A  minimal  span  solution  is  a  solution  for  a  subset  of  the  model,  i.e.  a  subset  of  the  rows  in  the  pow¬ 
ers  matrix  have  been  eliminated.  Furthermore,  the  subset  is  one  in  which  the  components  are  con¬ 
nected.  The  minimal  span  solution  is  inconsistent.  Finally,  if  any  component  is  removed  the  remaining 
components  are  consistent.  Stated  differently,  a  minimal  span  solution  is  inconsistent,  but  just  barely. 

The  set  of  minimal  span  solutions  are  derived  by  an  adaptation  of  the  Gaussian  elimination  algo¬ 
rithm  that  generates  the  full  solution.  A  minimal  span  solution  is  also  obtained  by  applying  a  sequence 
of  eliminate  operations  but  terminates  when  a  power  matrix  Mt  is  generated  that  is  either  inconsistent, 
or  is  not  reducable.  Recall  that,  in  general,  a  power  matrix  can  have  more  than  one  eliminate  operation 
applied  to  it.  Thus,  the  generation  of  all  possible  minimal  span  solutions  for  a  power  matrix  M0  forms 
a  tree  with  M0  being  the  root  and  each  leaf  being  a  power  matrix  that  satisfies  the  termination  condi¬ 
tion.  The  structure  of  each  non-leaf  node  is 


where  {El,...,EA  is  the  set  of  all  possible  eliminate  operations  that  can  be  applied  to  Mr 
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As  an  example,  the  power  matrix  for  the  model  in  Figure  3.8  is  shown  in  Figure  3.18. 
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FIGURE  3.18.  Power  matrix  for  model  shown  in  Figure  3.7 


One  minimum  span  solution  is  shown  by 
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Here,  the  minimal  span  solution  has  not  been  greyed  out.  The  row  labelled  inconsistent  caused  the 
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application  of  the  eliminate  sequence  to  terminate.  Note,  that  there  are  other  rows  that  could  be  elimi¬ 
nated,  but  when  this  row  was  produced  the  sequence  terminated  because  minimal  span  solutions  are 
being  generated.  Note,  also  that  the  unit  shown  in  the  inconsistent  row  is  1/hour  and  that  if  the  source 
of  this  row  where  replaced  with  a  two  port  actor  that  transformed  its  input  by  1/hour  then  this  inconsis¬ 
tency  would  be  removed. 

There  are  two  other  minimal  span  solutions  of  interest 
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These  two  minimal  span  solutions  are  related  in  that  they  have  eliminated  the  same  rows  in  the  power 
matrix.  The  first  indicated  that  the  inconsistency  could  be  fixed  by  applying  the  1/sec  transformation 
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on  the  relation  that  connects  HeatProduction.heat  to  AddSubtract.plus.  While  the  second  indicates  that 
the  inconsistency  could  be  removed  by  applying  the  second  transformation  to  the  relation  that  connects 
AddSubtract.minus  to  HeatExchanger.output. 

3.8.9  Implementing  the  Units  Constraint  Solver 


FIGURE  3.19.  Static  structure  of  the  classes  used  in  the  UnitConstraints  Solver 
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Appendix  A:  Expression  Evaluation 

The  evaluation  of  an  expression  is  done  in  two  steps.  First  the  expression  is  parsed  to  create  an 
abstract  syntax  tree  (AST)  for  the  expression.  Then  the  AST  is  evaluated  to  obtain  the  token  to  be 
placed  in  the  parameter.  In  this  appendix,  “token”  refers  to  instances  of  the  Ptolemy  II  token  classes,  as 
opposed  to  lexical  tokens  generated  when  an  expression  is  parsed. 

A.l  Generating  the  parse  tree 

In  Ptolemy  II  the  expression  parser,  called  PtParser,  is  generated  using  JavaCC  and  JJTree.  Jav¬ 
aCC  is  a  compiler-compiler  that  takes  as  input  a  file  containing  both  the  definitions  of  the  lexical 
tokens  that  the  parser  matches  and  the  production  rules  used  for  generating  the  parse  tree  for  an  expres¬ 
sion.  The  production  rules  are  specified  in  Backus  normal  form  (BNF).  JJTree  is  a  preprocessor  for 
JavaCC  that  enables  it  to  create  a  parse  tree.  The  parser  definition  is  stored  in  the  file  PtParser.jjt,  and 
the  generated  file  is  PtParser.java.  Thus  the  procedure  is 


PtParser.jjt 


^  JJTree 


PtParser.jj 


JavaCC 


PtParser.java 


Note  that  JavaCC  generates  top-down  parsers,  or  LL(k)  in  parser  terminology.  This  is  different 
from  yacc  (or  bison)  which  generates  bottom-up  parsers,  or  more  formally  LALR(l).  The  JavaCC  file 
also  differs  from  yacc  in  that  it  contains  both  the  lexical  analyzer  and  the  grammar  rules  in  the  same 
file. 

The  input  expression  string  is  first  converted  into  lexical  tokens,  which  the  parser  then  tries  to 
match  using  the  production  rules  for  the  grammar.  Each  time  the  parser  matches  a  production  rule  it 
creates  a  node  object  and  places  it  in  the  abstract  syntax  tree.  The  type  of  node  object  created  depends 
on  the  production  rule  used  to  match  that  part  of  the  expression.  For  example,  when  the  parser  comes 
upon  a  multiplication  in  the  expression,  it  creates  an  ASTPtProductNode.  If  the  parse  is  successful,  it 
returns  the  root  node  of  the  parse  tree  for  the  given  string. 

In  order  to  reduce  the  size  of  the  parse  tree,  nodes  that  representing  many  basic  operations  are 
designed  to  have  more  than  two  children,  even  for  binary  operations.  For  instance,  the  parse  tree  for 
the  expression  “2  +  3  +  “hello””  only  has  one  sum  node.  The  children  are  evaluated  in  the  correct  order 
for  the  associativity  of  the  operator.  In  this  case,  the  expression  evaluates  to  the  string  token  with  value 
“5hello”. 

Note  that  although  functions  and  constants  are  registered  with  the  parser,  the  parser  does  not  actu¬ 
ally  resolve  the  values  of  identifiers.  This  resolution  is  performed  when  the  parse  tree  is  actually  eval¬ 
uated.  The  evaluation  process  only  resorts  to  registered  functions  and  constants  if  there  are  no 
identifiers  defined  in  the  model.  This  prevents  registered  functions  and  constants  from  unexpectedly 
shadowing  parameters  in  the  model,  leading  to  unexpected  behavior.  It  also  allows  new  functions  and 
constants  to  be  registered  without  changing  the  behavior  of  existing  models.  Essentially,  functions  and 
constants  registered  with  the  parser  act  as  a  global  scope  in  which  all  models  exist  with  their  own  local 
scopes. 

One  of  the  key  properties  of  the  expression  language  is  the  ability  to  refer  to  other  parameters  by 
name.  Since  an  expression  that  refers  to  other  parameters  may  need  to  be  evaluated  several  times 


86 


Ptolemy  II 


Data  Package 


(when  the  referred  parameter  changes),  it  is  important  that  the  parse  tree  does  not  need  to  be  recreated 
every  time.  The  classes  for  representing  the  parse  tree  are  designed  to  carry  little  state,  other  than  the 
representation  of  an  expression.  Generally  speaking,  users  of  parse  trees,  such  as  the  Variable  class, 
cache  parse  trees  for  re-evaluation.  A  new  parse  tree  is  only  generated  when  the  expression  changes. 
Note,  however  that  the  Parser  itself  is  not  cached,  since  it  contains  a  significant  amount  of  internal 
state. 


A.2  Traversing  the  parse  tree 


After  being  generated,  the  parse  tree  can  be  manipulated  or  traversed,  in  order  to  analyze  various 
properties  of  the  original  expression.  In  order  to  facilitate  traversal  of  the  parse  tree,  the  classes  repre¬ 
senting  parse  tree  nodes  implement  a  visitor  design  pattern.  Each  node  implements  a  visit()  method 
that  accepts  an  instance  of  the  ParseTreeVisitor  class.  When  the  visit()  method  of  a  node  is  invoked, 
the  node  calls  an  appropriate  method  of  the  visitor  corresponding  to  the  same  node  class.  The  visitor 
can  then  operate  on  the  node  and  recursively  invoke  the  visit  method  of  child  nodes  to  traverse  the 
entire  parse  tree.  This  pattern  allows  the  entire  logic  of  a  parse  tree  traversal  to  be  placed  in  a  single 
class  that  is  largely  decoupled  from  the  parse  tree  itself.  Several  visitors  have  been  written,  and  are 
described  below. 


A.2.1  Evaluating  the  parse  tree 


Parse  trees  are  evaluated  using  a  visitor  implemented  by  the  ParseTreeEvaluator  class.  The  parse 
tree  is  evaluated  in  a  bottom  up  manner  as  each  node  can  only  determine  its  type  after  the  types  of  all 
its  children  have  been  resolved.  As  an  example  consider  the  input  string  2  +  3.5.  The  parse  tree 
returned  from  the  parser  will  look  like  this: 


(sum) 


Clcaf)|ntT0kcn(2)  DoublcTokcn(3.5) 


♦ 

I 

I  Tree  evaluation 


During  evaluation,  the  value  of  the  leaf  nodes  is  first  determined,  which  is  trivial  in  this  case,  since  the 
values  of  leaves  are  constants.  These  values  are  then  propagated  upwards,  determining  the  value  of 
each  internal  node,  until  the  value  of  the  root  node  is  returned.  In  this  case  a  DoubleToken  with  value 
5.5  will  be  returned  as  the  result.  If  an  error  occurs  during  evaluation  of  the  parse  tree,  an  IllegalAc- 
tionException  is  thrown  with  a  error  message  about  where  the  error  occurred. 

When  the  ParseTreeEvaluator  reaches  a  instance  of  the  ASTPtLeafNode  class  that  references  an 
identifier,  it  resolves  the  identifier  into  a  value  through  the  ParserScope  interface.  By  resolving  the  val¬ 
ues  of  identifiers  through  a  ParserScope,  identifiers  can  be  resolved  in  different  ways  depending  on 
how  the  expression  is  used.  This  mechanism  is  used,  for  instance  to  implement  the  evaluation  of  func¬ 
tion  closures  and  the  Expression  actors,  which  interpret  expressions  differently  from  parameters.  Only 
if  an  identifier  is  not  found  in  scope,  is  the  identifier  resolved  against  the  constants  registered  in  the 
parser. 
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When  the  ParseTreeEvaluator  reaches  a  instance  of  the  ASTPtFunctionApplicationNode  class,  it 
is  handled  similarly  to  a  leaf  node  with  an  identifier.  The  name  of  the  function  is  resolved  in  the  scope, 
in  case  the  identifier  refers  to  a  function  closure,  an  array  token,  or  a  matrix  token.  If  the  identifier  is 
not  found  in  scope,  then  reflection  to  look  for  that  function  in  the  list  of  classes  registered  with  the 
parser. 

A.2.2  Inferring  types  of  parse  trees 

The  ParseTreeTypelnference  class  visits  parse  trees  to  analyze  the  type  of  token  resulting  from 
evaluation.  For  the  most  part,  this  operates  the  same  as  the  ParseTreeEvaluator  class,  using  a  Parser- 
Scope  to  resolve  the  types  of  identifiers.  If  identifiers  are  not  present  in  scope,  then  they  are  searched 
for  in  the  constants  or  functions  registered  with  the  parser. 

One  difficulty  with  type  inference  is  that  the  type  of  tokens  returned  from  a  function  invocation 
can  often  not  be  determined  from  the  return  type  of  the  Java  method.  For  instance,  if  the  Java  method 
has  a  return  type  corresponding  to  the  Token  base  class,  then  any  token  class  might  be  produced.  To 
resolve  the  types  of  these  methods,  the  ParseTreeTypelnference  class  uses  Java  reflection  to  find  a 
method  with  a  corresponding  name  that  gives  the  return  type  of  the  original  function.  For  instance,  the 
max()  method  in  the  UtilityFunctions  class  returns  the  maximum  value  of  an  input  ArrayToken.  Since 
the  ArrayToken  can  contain  any  type,  the  UtilityFunctions  class  contains  a  parallel  maxRetumType() 
method  that  takes  a  single  Type  argument,  and  returns  a  type.  During  type  inference,  this  method  is 
found  and  invoked  to  properly  infer  the  type  returned  from  the  max()  method. 

A.2.3  Retrieving  identifiers  in  parse  trees 

The  ParseTreeFreeVariableCollector  class  visits  parse  trees  and  extracts  the  names  of  all  identifi¬ 
ers  that  need  to  be  resolved  to  values  outside  of  the  expression.  In  particular,  it  does  not  return  the 
names  of  identifiers  that  are  bound  to  the  arguments  of  function  closures.  These  identifiers  are  not 
accessible  outside  of  the  expression.  As  an  example,  the  expression  “foo  +  bar”  has  two  free  variables 
that  must  be  given  values.  However,  the  expression  “function(foo:int)  foo  +  bar”  has  only  one  free 
variable,  since  the  identifier  “foo”  is  bound  to  the  argument  of  the  function  closure. 

A.2.4  Specializing  parse  trees 

The  ParseTreeSpecializer  class  visit  parse  trees  and  simplifies  them.  Primarily,  this  involves 
replacing  identifier  references  in  leaf  nodes  with  constant  values.  This  operation  is  an  important  part  of 
creating  FunctionTokens,  since  the  expression  inside  a  function  closure  can  only  reference  identifiers 
that  are  explicitly  bound  to  arguments  of  the  FunctionToken.  By  specializing  the  parse  tree  for  the 
expression,  we  ensure  that  the  FunctionToken  has  no  dependence  on  the  scope  in  which  it  was  created. 
The  specializer  also  analyses  the  parse  tree,  finding  any  internal  nodes  that  are  constant  after  replacing 
identifiers.  These  constant  nodes  are  evaluated  and  replaced  by  leaf  nodes. 

A.3  Node  types 

There  are  currently  fourteen  node  classes  used  in  creating  the  syntax  tree.  For  some  of  these  nodes 
the  types  of  their  children  are  fairly  restricted  and  so  type  and  value  resolution  is  done  in  the  node.  For 
others,  the  operators  that  they  represent  are  overloaded,  in  which  case  methods  in  the  token  classes  are 
called  to  resolve  the  node  type  and  value  (i.e.  the  contained  token).  By  type  resolution  we  are  referring 
to  the  type  of  the  token  to  be  stored  in  the  node. 
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ASTPtArrayConstructNode.  This  node  is  created  when  an  array  construction  sub-expression  is  parsed. 
It  contains  one  child  node  for  each  element  of  the  array. 

ASTPtAssignmentNode .  This  node  is  created  when  an  assignment  is  parsed.  It  contains  exactly  two 
children.  The  first  child  is  an  ASTPtLeafNode  corresponding  to  the  identifier  being  assigned  to  and  the 
second  child  corresponds  to  the  assigned  expression. 

ASTPtBitwiseNode.  This  node  is  created  when  a  bitwise  operation  (&,  ,  A)  is  parsed.  It  contains  at  least 
two  child  nodes,  and  each  element  has  the  same  operation  applied. 

ASTPtFunctionApplicationNode.  This  node  is  created  when  a  function  is  invoked.  The  first  child  is 
always  a  node  giving  the  function  that  will  be  invoked.  For  built-in  functions,  this  child  will  be  a  leaf 
node  containing  an  identifier  naming  the  function.  The  remaining  children  correspond  to  arguments  of 
application  from  left  to  right. 

ASTPtFunctionDefinitionNode.  This  node  is  created  when  a  function  definition  is  parsed.  For  each 
argument  of  the  function  definition,  there  are  two  child  nodes.  The  first  child  node  is  a  leaf  node  that 
contains  an  identifier  for  the  argument  name,  while  the  second  gives  an  expression  for  the  type  of  the 
argument.  If  no  type  is  specified,  then  a  child  node  is  created  that  evaluates  to  a  type  of  general.  The 
last  child  node  contains  an  expression  tree  that  defines  the  function. 

ASTPtFunctionallfNode.  This  is  created  when  a  functional  if  is  parsed.  This  node  always  has  three 
children,  the  first  for  the  boolean  condition  and  the  remaining  two  children  for  each  branch  of  the 
expression. 

ASTPtLeafNode.  This  represents  the  leaf  nodes  in  the  AST.  The  node  contains  either  a  token  corre¬ 
sponding  to  constant  values,  or  a  string  name  for  an  identifier  in  the  expression.  This  node  contains  no 
children. 

ASTPtLogicalNode.  This  node  is  created  when  a  logical  operation  (&&,  ||)  is  parsed.  It  contains  at  least 
two  child  nodes,  and  each  element  has  the  same  operation  applied. 

ASTPtMatrixConstructNode.  This  is  created  when  a  matrix  construction  sub-expression  is  parsed.  If 
the  matrix  is  specified  explicitly,  then  this  node  contains  one  child  node  for  each  element  of  the  matrix. 
If  the  matrix  is  specified  using  sequence  notation  for  each  row,  then  the  node  contains  three  children 
for  each  row  of  the  matrix. 

ASTPtMethodCallNode.  This  is  created  when  a  method  call  is  parsed.  The  first  child  corresponds  to 
the  value  the  method  is  being  invoked  on,  while  the  remaining  children  correspond  to  arguments  of  the 
method  call. 

ASTPtProductNode.  This  is  created  when  an  arithmatic  product  operation  (*,  /,%)  is  parsed.  It  contains 
at  least  two  child  nodes,  although  the  same  operation  need  not  be  applied  to  each  child.  The  node  con¬ 
tains  a  list  of  operations  corresponding  to  the  individual  operations  that  need  to  be  applied.  This  list 
has  one  fewer  element  than  the  number  of  children. 

ASTPtRecordConstructNode.  This  is  created  when  a  record  construct  sub-expression  is  parsed.  It  con¬ 
tains  one  node  for  each  value  in  the  record  and  a  list  of  names  corresponding  to  the  label  for  each 
value. 

ASTPtRelationalNode.  This  is  created  when  one  of  the  relational  operators  (!=,  ==,  >,  >=,  <,  <=)  is 
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parsed.  It  contains  exactly  two  child  nodes. 

ASTPtRootNode.  Parent  class  of  all  the  other  nodes. 

ASTPtSumNode.  This  is  created  when  a  arithmatic  summation  operation  (+,  -)  is  parsed.  It  contains  at 
least  two  child  nodes,  although  the  same  operation  need  not  be  applied  to  each  child.  The  node  con¬ 
tains  a  list  of  operations  corresponding  to  the  individual  operations  that  need  to  be  applied.  This  list 
has  one  fewer  element  than  the  number  of  children. 

ASTPtUnaryNode.  This  is  created  when  a  unary  negation  operator  (!,  -)  is  parsed.  It  always  contains 

exactly  one  child  node. 

A.4  Extensibility 

The  Ptolemy  II  expression  language  has  been  designed  to  be  extensible.  The  main  mechanisms  for 
extending  the  functionality  of  the  parser  is  the  ability  to  register  new  constants  with  it  and  new  classes 
containing  functions  that  can  be  called.  However  it  is  also  possible  to  add  and  invoke  methods  on 
tokens,  or  to  even  add  new  rules  to  the  grammar,  although  both  of  these  options  should  only  be  consid¬ 
ered  in  rare  situations. 

To  add  a  new  constant  that  the  parser  will  recognize,  invoke  the  method  registerConstant(String 
name,  Object  value)  on  the  parser.  This  is  a  static  method  so  whatever  constant  you  add  will  be  visible 
to  all  instances  of  PtParser  in  the  Java  virtual  machine.  The  method  works  by  converting,  if  possible, 
whatever  data  the  object  has  to  a  token  and  storing  it  in  a  hashtable  indexed  by  name.  By  default,  only 
the  constants  in  java.lang.Math  are  registered. 

To  add  a  new  Class  to  the  classes  searched  for  a  a  function  call,  invoke  the  method  register- 
Class(String  name)  on  the  parser.  This  is  also  a  static  method  so  whatever  class  you  add  will  be 
searched  by  all  instances  of  PtParser  in  the  JVM.  The  name  given  must  be  the  fully  qualified  name  of 
the  class  to  be  added,  for  example  “java.lang.Math”.  The  method  works  by  creating  and  storing  the 
Class  object  corresponding  to  the  given  string.  If  the  class  does  not  exist  an  exception  is  thrown.  When 
a  function  call  is  parsed,  an  ASTPtFunctionNode  is  created.  Then  when  the  parse  tree  is  being  evalu¬ 
ated,  the  node  obtains  a  list  of  the  classes  it  should  search  for  the  function  and,  using  reflection, 
searches  the  classes  until  it  either  finds  the  desired  function  or  there  are  no  more  classes  to  search.  The 
classes  are  searched  in  the  same  order  as  they  were  registered  with  the  parser,  so  it  is  better  to  register 
those  classes  that  are  used  frequently  first. 
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4.1  Introduction 

The  Ptolemy  II  kernel  provides  extensive  infrastructure  for  creating  and  manipulating  clustered 
graphs  of  a  particular  flavor.  Mathematical  graphs,  however,  are  simpler  structures  that  consist  of 
nodes  and  edges,  without  hierarchy.  Edges  link  pairs  of  nodes,  and  therefore  are  much  simpler  than  the 
relations  of  the  Ptolemy  II  kernel.  Moreover,  in  mathematical  graphs,  no  distinction  is  made  between 
multiple  edges  that  may  be  adjacent  to  a  node,  so  the  ports  of  the  Ptolemy  II  kernel  are  not  needed.  A 
large  number  of  algorithms  have  been  developed  that  operate  on  mathematical  graphs,  and  many  of 
these  prove  extremely  useful  in  support  of  scheduling,  type  resolution,  and  other  operations  in  Ptolemy 
II.  Thus,  we  have  created  the  graph  package,  which  provides  efficient  data  structures  for  mathematical 
graphs,  and  collects  algorithms  for  operating  on  them.  At  this  time,  the  collection  of  algorithms  is 
nowhere  near  as  complete  as  in  some  widely  used  packages,  such  as  LEDA  [87].  But  this  package  will 
serve  as  a  repository  for  a  growing  suite  of  algorithms. 

The  graph  package  provides  basic  infrastructure  for  both  undirected  and  directed  graphs.  Acyclic 
directed  graphs,  which  can  be  used  to  model  complete  partial  orders  (CPOs)  and  lattices,  are  also  sup¬ 
ported  with  more  specialized  algorithms. 

The  graphs  constructed  using  this  package  are  designed  to  provide  broad  support  for  algorithms 
that  operate  on  generic,  mathematical  graphs.  A  typical  use  of  this  package  is  to  construct  a  graph  that 
represents  the  topology  of  a  CompositeEntity,  run  a  graph  algorithm,  and  extract  useful  information 
from  the  result.  For  example,  a  graph  might  be  constructed  that  represents  data  precedences,  and  a 
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topological  sort  might  be  used  to  generate  a  schedule.  In  this  kind  of  application,  the  hierarchy  of  the 
original  clustered  graph  is  flattened,  so  nodes  in  the  graph  represent  only  opaque  entities. 

4.2  Classes  and  Interfaces  in  the  Graph  Package 

Figures  4.  land  4.2  show  the  class  diagram  of  the  graph  package.  The  classes  Node,  Edge,  Graph, 
DirectedGraph  and  DirectedAcyclicGraph  support  graph  construction  and  provide  graph  algorithms. 
Currently,  only  a  limited  set  of  algorithms  are  implemented;  other  algorithms  will  be  added  as  needed. 
The  CPO  interface  defines  the  basic  CPO  operations,  and  the  class  DirectedAcyclicGraph  implements 
this  interface.  An  instance  of  DirectedAcyclicGraph  is  also  a  finite  CPO  where  all  the  elements  and 
order  relations  are  explicitly  specified.  Defining  the  CPO  operations  in  an  interface  allows  future 
expansion  to  support  infinite  CPOs  and  finite  CPOs  where  the  elements  are  not  explicitly  enumerated. 
The  InequalityTerm  interface  and  the  Inequality  class  model  inequality  constraints  over  the  CPO.  The 
details  of  the  constraints  will  be  discussed  later.  The  InequalitySolver  class  provides  an  algorithm  to 
solve  a  set  of  constraints.  This  is  used  by  the  Ptolemy  II  type  system,  but  other  uses  may  arise. 

None  of  the  classes  in  this  package  is  synchronized.  If  multiple  threads  access  a  graph  or  analysis 
or  data  structure  concurrently,  external  synchronization  will  be  needed. 

4.2.1  Element  and  ElementList 

A  graph  element  consists  of  an  optional  weight  (an  arbitrary  object  that  is  associated  with  the  ele¬ 
ment).  We  say  that  an  element  is  unweighted  if  it  does  not  have  an  assigned  weight. 

An  element  list  is  a  list  of  graph  elements.  This  class  manages  the  storage  and  weight  information 
associated  with  a  list  of  unique  graph  elements.  This  class  is  normally  for  use  internally  within  graph 
classes.  The  list  is  implemented  as  a  HashMap. 

4.2.2  Labeled  Lists 

LabeledList  is  a  type  of  ElementList  that  it  is  used  as  a  support  class  for  graphs  in  this  package  and 
allows  one  to  construct  efficient  mappings  from  subsets  of  nodes  and/or  edges  into  arbitrary  values.  A 
LabeledList  is  a  list  of  unique  objects  (elements)  with  an  assignment  from  the  elements  into  consecu¬ 
tive  integer  labels.  The  labels  are  consecutive  integers  between  0  and  N -  1  inclusive,  where  N  is  the 
total  number  of  elements  in  the  list.  This  list  features  0(  1 )  list  insertion,  0(1)  testing  for  membership 
in  the  list,  0(  1 )  access  of  a  list  element  from  its  associated  label,  and  (9(1)  access  of  a  label  from  its 
corresponding  element.  The  element  labels  are  useful,  for  example,  in  creating  mappings  from  list  ele¬ 
ments  into  elements  of  arbitrary  arrays.  More  generally,  element  labels  can  be  used  to  maintain  arbi¬ 
trary  m  -dimensional  matrices  that  are  indexed  by  the  list  elements  (via  the  associated  element  labels). 

Element  labels  maintain  their  consistency  (remain  constant)  during  periods  when  no  elements  are 
removed  from  the  list.  When  elements  are  removed,  the  labels  assigned  to  the  remaining  elements  may 
change. 

Elements  themselves  must  be  non-null  and  distinct,  as  determined  by  the  equals  method. 

This  class  supports  all  required  operations  of  the  list  interface,  except  for  the  subList  operation, 
which  results  in  an  UnsupportedOperationException. 

4.2.3  Node 

This  class  derived  from  Element  models  a  vertex  for  inclusion  in  undirected  or  directed  graphs. 
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More  specifically,  all  vertices  in  a  graph  are  Node  instances,  and  each  node  has  an  optional  weight  (an 
arbitrary  object  that  is  associated  with  the  node).  We  say  that  a  node  is  unweighted  if  it  does  not  have 
an  assigned  weight.  It  is  an  error  to  attempt  to  access  the  weight  of  an  unweighted  node.  Node  weights 
must  be  genuine  (non-null)  objects. 

4.2.4  Edge 

This  class  derived  from  Element  represents  a  weighted  or  unweighted  edge  for  a  directed  or  undi¬ 
rected  graph.  The  connectivity  of  edges  is  specified  by  source  nodes  and  sink  nodes.  A  directed  edge  is 
directed  from  its  source  node  to  its  sink  node.  For  an  undirected  edge,  the  source  node  is  simply  the 
first  node  that  was  specified  when  the  edge  was  created,  and  the  sink  node  is  the  second  node.  This 
convention  allows  undirected  edges  to  later  be  converted  in  a  consistent  manner  to  directed  edges,  if 
desired. 

On  creation  of  an  edge,  an  arbitrary  object  can  be  associated  with  the  edge  as  the  weight  of  the 
edge.  We  say  that  an  edge  is  unweighted  if  it  does  not  have  an  assigned  weight.  It  is  an  error  to  attempt 
to  access  the  weight  of  an  unweighted  edge. 

Self-loop  edges  (edges  whose  source  and  sink  nodes  are  identical)  are  allowed. 

The  source  node  and  sink  node  of  an  edge  cannot  be  changed. 

4.2.5  Graph 

This  class  models  a  graph  with  optionally-weighted  edges  and  nodes.  Nodes  and  edges  of  a  graph 
are  instances  of  Node  and  Edge,  respectively.  Thus,  each  node  or  edge  may  have  a  weight  associated 
with  it.  The  nodes  (edges)  in  a  graph  are  always  distinct,  but  their  weights  need  not  be. 

Each  node  (edge)  has  a  unique,  integer  label  associated  with  it.  These  labels  can  be  used,  for  exam¬ 
ple,  to  index  arrays  and  matrixes  whose  rows/columns  correspond  to  nodes  (edges).  Both  directed  and 
undirected  graphs  can  be  implemented  using  this  class.  In  directed  graphs,  the  order  of  nodes  specified 
to  the  addEdge  method  is  relevant,  whereas  in  undirected  graphs,  the  order  is  unimportant.  Support  for 
both  undirected  and  directed  graphs  follows  from  the  combined  support  for  these  in  the  underlying 
Node  and  Edge  classes.  The  DirectedGraph  class  provides  more  thorough  support  for  directed  graphs. 

The  same  node  can  exist  in  multiple  graphs,  but  any  given  graph  can  contain  only  one  instance  of 
the  node.  Node  labels,  however,  are  local  to  individual  graphs.  Thus,  the  same  node  may  have  different 
labels  in  different  graphs.  Furthermore,  the  label  assigned  in  a  given  graph  to  a  node  may  change  over 
time  (if  the  set  of  nodes  in  the  graph  changes).  The  weight  of  a  node  is  identical  for  all  instances  of  the 
node  in  multiple  graphs.  All  of  this  holds  for  edges  all  well.  The  same  weight  may  be  shared  among 
multiple  nodes  and  edges. 

Multiple  edges  in  a  graph  can  connect  the  same  pair  of  nodes.  Thus,  multigraphs  are  supported. 

Once  assigned,  node  and  edge  weights  should  not  be  changed  in  ways  that  affect  comparison  under 
the  equals  method  Otherwise,  unpredictable  behavior  may  result. 

4.2.6  Directed  Graphs 

The  DirectedGraph  class  is  derived  from  Graph.  The  addEdge  method  in  DirectedGraph  adds  a 
directed  edge  to  the  graph.  In  this  class,  the  direction  of  the  edge  is  said  to  go  from  a  source  node  to  a 
sink  node. 

The  computation  of  transitive  closure  operations  is  implemented  in  this  class.  The  transitive  clo¬ 
sure  is  internally  stored  as  a  two-dimensional  boolean  matrix,  whose  indices  correspond  to  node  labels. 
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The  entry  (/,/)  is  true  if  and  only  if  there  exists  a  path  from  the  node  with  label  i  to  the  node  with  label 
j.  This  matrix  is  not  exposed  at  the  public  interface;  instead,  it  is  used  by  this  class  and  its  subclass  to 
do  other  operations.  Once  the  transitive  closure  matrix  is  computed,  graph  operations  like  reachableN- 
odes  can  be  easily  accomplished. 

Some  methods  in  this  class  have  two  versions,  one  that  operates  on  graph  nodes,  and  another  that 
operations  on  node  weights.  The  latter  form  is  called  the  weights  version.  More  specifically,  the 
weights  version  of  an  operation  takes  individual  node  weights  or  arrays  of  weights  as  arguments,  and, 
when  applicable,  returns  individual  weights  or  arrays  of  weights. 

Multiple  edges  in  a  graph  can  be  directed  between  the  same  pair  of  nodes  (in  the  same  direction). 
Thus,  directed  multigraphs  are  supported. 
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+Graph() 

+Graph(nodeCount :  int) 

+Graph(nodeCount :  int,  edgeCount :  int) 

+addAnalysis(analysis  :  Analysis) :  void 
+addEdge(edge  :  Edge) :  Edge 

+addEdge(node1  :  Node,  node2  :  Node) :  Edge  - 

+addEdge(node1  :  Node,  node2  :  Node,  weight :  Object) :  Edge  0..n 

+addEdge(weight1  :  Object,  weight2  :  Object) :  Collection 

+addEdge(weight1  :  Object,  weight2  :  Object,  newEdgeWeight :  Object) :  Collection 
+addEdges(edgeCollection  :  Collection) :  void 
+addGraph(graph  :  Graph) :  boolean 
+addNode() :  Node 

+addNode(node  :  Node) :  Node  _ 

+addNodes(nodeCollection  :  Collection]) :  void 
+addNodeWeight(weight :  Object) :  Node 
+addNodeWeights(weightCollection  :  Collection) :  Collection 
+changeCount() :  long 
+cloneAs(graph  :  Graph) :  Graph 
+connectedComponents() :  Collection 
+containsEdge(edge  :  Edge) :  boolean 
+containsEdgeWeight(weight :  Object) :  boolean 
+containsNode(node  :  Node) :  boolean 
+containsNodeWeight(weight :  Object) :  boolean 
+edge(label  :  int) :  Edge 
+edge(weight :  Object) :  Edge 
+edgeCount() :  int 
+edgeLabel(edge  :  Edge) :  int 
+edgeLabel(weight :  Object) :  int 
+edges() :  Collection 

+edges(collection  :  Collection) :  Collection 
+edges(weight :  Object) :  Collection 
+edgeWeight(label  :  int) :  Object 
+hidden(edge  :  Edge) :  boolean 
+hiddenEdgeCount() :  int 
+hiddenEdges() :  Collection 
+hideEdge(edge  :  Edge) :  boolean 

+incidentEdgeCount(node  :  Node)  ®-n 

+incidentEdges(node  :  Node) :  Collection 

+neighborEdges(node1  :  Node,  node2  :  Node) :  Collection 

+neighbors(node  :  Node) :  Collection 

+node(label  :  int) :  Node 

+node(weight :  Object) :  Node 

+nodeCount() :  int 

+nodeLabel(node  :  Node) :  int 

+nodeLabel(weight :  Object) :  int 

+nodes() :  Collection 

+nodes(collection  :  Collection) :  Collection 
+nodes(weight :  Object) :  Collection 
+nodeWeight(label  :  int) :  Object 

+removeEdge(edge  :  Edge) :  boolean  0..n 

+removeNode(node  :  Node) :  boolean 

+restoreEdge(edge  :  Edge) :  boolean 

+selfLoopEdgeCount() :  int 

+selfLoopEdgeCount(node  :  Node) :  int 

+selfLoopEdges(node  :  Node) :  Collection 

+selfLoopEdges() :  Collection 

+subgraph(collection  :  Collection) :  Graph 

+subgraph(nodeCollection  :  Collection,  edgeCollection  :  Collection) :  Graph 
+validateWeight(edge  :  Edge) :  boolean 
+validateWeight(edge  :  Edge,  oldWeight :  Object) :  boolean 
+validateWeight(node  :  Node) :  boolean 
+validateWeight(node  :  Node,  oldWeight :  Object) :  boolean 
+validateEdgeWeight(object :  Object) :  boolean 
+validateNodeWeight(object :  Object) :  boolean 
+weightArray(elementCollection  :  Collection) :  Object[] 

#_addEdge(node1  :  Node,  node2  :  Node,  weighted  :  boolean,  weight :  Object) :  Edge  ” 

#_connect(edge  :  Edge,  node  :  Node) :  void 

#_connectEdge(edge  :  Edge) :  void 

#_disconnect(edge  :  Edge,  node  :  Node) :  void 

#_disconnectEdge(edge  :  Edge) :  void 

#_emptyGraph() :  Graph 

#_initializeAnalyses() :  void 

#_registerChange() :  void 

#_registerEdge(edge  :  Edge) :  void 

#_registerNode(node  :  Node) :  void 


q  n  |  ElementList 


FIGURE  4.1.  Core  of  the  graph  package. 
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DirectedGraph 

#_transitiveClosure  :  boolean[][] 

+DirectedGraph() 

+DirectedGraph(nodeCount :  int) 
+DirectedGraph(nodeCount :  int,  edgeCount :  int) 
+backwardReachableNodes(nodeCollection  :  Collection) 
+backwardReachableNodes(node  :  Node) 
+backwardReachableNodes(weight :  Object) 
+backwardReachableNodes(weights  :  Object[]) :  ObjectQ 
+cycleNodeCollection() :  Collection 
+cycleNodes() :  ObjectQ 

+edgeExists(node1  :  Node,  node2  :  Node) :  boolean 
+edgeExists(weight1  :  Object,  weight2  :  Object) :  boolean 
+inputEdgeCount(node  :  Node) :  int 
+inputEdges(node  :  Node) :  Collection 
+isAcyclic() :  boolean 
+outputEdgeCount(node  :  Node) :  int 
+outputEdges(node  :  Node) :  Collection 
+predecessorEdges(n1  :  Node,  n2  :  Node) :  Collection 
+predecessors(node  :  Node) :  Collection 
+reachableNodes(nodeCollection  :  Collection) :  Collection 
+reachableNodes(node  :  Node) :  Collection 
+reachableNodes(weight :  Object) :  ObjectQ 
+reachableNodes(weights  :  ObjectQ) :  ObjectQ 
+sccDecomposition() :  DirectedGraphQ 
+selfLoopEdgeCount(node  :  Node) :  int 
+sinkNodeCount() :  int 
+sinkNodes() :  Collection 
+sourceNodeCount() :  int 
+sourceNodes() :  Collection 
+successorEdges(n1  :  Node,  n2  :  Node) :  Collection 
+successors(node  :  Node) :  Collection 
+toDirectedAcyclicGraph() :  DirectedAcyclicGraph 
+topologicalSort(nodeCollection  :  Collection) :  List 
+topologicalSort(weights  :  ObjectQ) :  ObjectQ 
+transitiveClosure() :  booleanQQ 

DirectedAcyclicGraph 


+DirectedAcyclicGraph() 
+DirectedAcyclicGraph(nodeCount :  int) 

+bottom() :  Object 

+compare(e1  :  Object,  e2  :  Object) :  int 
+downSet(e  :  Object) :  Object[] 
+greatestElement(subset :  Object[]) :  Object 
+greatestLowerBound(subset :  Object[]) :  Object 
+greatestLowerBound(e1  :  Object,  e2  :  Object) :  Object 
+isLattice() :  boolean 
+leastElement(subset :  Object[]) :  Object 
+leastUpperBound(subset :  Object[]) :  Object 
+leastUpperBoundObject(e1  :  Object,  e2  :  Object) 
+top() :  Object 
+topologicalSort() :  Object[] 

+topologicalSort(weights  :  Object[]) :  Object[] 

+upSet(e  :  Object) :  ObjectQ 


LabeledList 


+LabeledList() 

+add(index  :  int,  element :  Object) :  void 
+add(element :  Object) :  boolean 
+addAII(collection  :  Collection) :  boolean 
+addAII(index  :  int,  collection  :  Collection) :  boolean 
+clear() :  void 

+contains(object :  Object) :  boolean 
+containsAII(collection  :  Collection) :  boolean 
+get(label  :  int) :  Object 
+indexOf(element :  Object) :  int 
+isEmpty() :  boolean 
+iterator() :  Iterator 
+label(element :  Object) :  int 
+lastlndexOf(element :  Object) :  int 
+listlterator() :  Listlterator 
+listlterator(index  :  int) :  Listlterator 
+remove(label  :  int) :  Object 
+remove(element :  Object) :  boolean 
+removeAII(c  :  Collection) :  boolean 
+retainAII(c  :  Collection) :  boolean 
+set(index  :  int,  element :  Object) :  Object 
+size() :  int 

+subList(from Index  :  int,  tolndex  :  int) :  List 
+toArray() :  Object[] 

+toArray(array  :  ObjectQ) :  ObjectQ 

+toString(delimiter :  String,  includeLabels  :  boolean) :  String 


ElementList 


+ElementList(descriptor :  String,  graph  :  Graph) 
+ElementList(descriptor :  String,  graph  :  Graph,  elementCount :  int) 
+cancelWeight(element :  Element) :  boolean 
+changeWeight(element :  Element) :  boolean 
+clear() :  void 

+containsWeight(weight :  Object) :  boolean 
+element(weight :  Object) :  Element 
+elements() :  Collection 
+elements(weight :  Object) :  Collection 
+registerWeight(element :  Element) :  void 
+remove(element :  Element) :  boolean 

+validateWeight(element :  Element,  oldWeight :  Object) :  boolean 


«lnterface» 

CPO 
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FIGURE  4.2.  Core  of  the  graph  package  (Cont.). 
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4.2.7  Graph  Mappings 


FIGURE  4.3.  Classes  in  the  graph. mapping  package. 


4.2.8  Graph  Analysis 

The  Analysis  package  implements  the  Strategy  Design  Pattern.  This  design  pattern  consists  of 
decoupling  an  algorithm  from  its  host,  and  encapsulating  the  algorithm  into  a  separate  class.  More  sim¬ 
ply  put,  an  object  and  its  behavior  are  separated  and  put  into  two  different  classes.  This  allows  the  user 
to  switch  the  algorithm  that  she/he  is  using  at  any  time.  There  are  several  advantages  to  doing  this. 
First,  if  you  have  several  different  behaviors  that  you  want  an  object  to  perform,  it  is  much  simpler  to 
keep  track  of  them  if  each  behavior  is  a  separate  class,  and  not  buried  in  the  body  of  some  method. 
Should  you  ever  want  to  add,  remove,  or  change  any  of  the  behaviors,  it  is  a  much  simpler  task,  since 
each  one  is  its  own  class.  Each  such  behavior  or  algorithm  encapsulated  into  its  own  class  is  called  a 
Strategy. 

In  other  words  strategies  define  a  family  of  algorithms,  encapsulate  each  one,  and  make  them 
interchangeable.  Strategy  lets  the  algorithm  vary  independently  from  clients  that  use  it. 


Heterogeneous  Concurrent  Modeling  and  Design 


97 


Graph  Package 


Classes  in  ptolemy.graph.analysis  consists  of  different  wrappers  in  which  a  client  can  plug  a 
requested  strategy/algorithm  for  an  analysis.  Strategies  for  a  given  analysis  implement  the  same  inter¬ 
face  defined  in  ptolemy.graph.analysis. analyzer. 

Therefore  from  now  on  we  will  use  the  name  analyzer  for  all  the  strategies  that  implement  the 
same  interface  and  therefore  solve  the  same  problem.  Analysis  classes  access  the  plugged-in  strategy 
class  through  these  interfaces.  The  strategies  classes  are  defined  in  ptolemy.graph.analysis. strategy.  In 
addition,  the  analysis  classes  provide  default  constructors  which  use  predefined  strategies  for  those  cli¬ 
ents  who  do  not  want  to  deal  with  different  strategies.  This  may  introduce  some  limitations  imposed  by 
the  used  strategy.  The  documentation  of  such  constructors  should  reflect  the  limitations,  if  any. 

Finally,  strategies  can  be  instantiated  and  used  independently.  In  this  case  the  client  will  lose  the 
possibility  of  dynamically  changing  the  analyzer  for  the  associated  analysis,  which  would  not  exist  at 
all,  and  there  will  be  no  default  constructor  therefore  the  client  need  to  be  familiar  with  the  strategy 
that  she/he  is  using. 

In  the  base  class,  methods  are  provided  in  order  to  dynamically  change  the  analyzer  of  the  current 
analysis  and  also  to  check  if  a  given  analyzer  is  applicable  to  the  given  analysis. 

Analyzers  that  can  be  used  in  these  analyses  are  specialized  versions  of  analyzers  of  the  type 
ptolemy.graph.analysis. analyzer.  GraphAnalyzer 

Classes  in  ptolemy.graph.analysis. analyzer  are  the  interfaces  for  different  strategies  (algorithms) 
used  for  the  analysis.  A  list  of  available  analyses  follows: 

Single  source  longest  path,  self  loop,  source  node  and  sink  node,  transitive  closure,  cycle  mean 
(maximum  and  minimum),  cycle  existence,  all-pairs  shortest  path,  negative-weight  cycle  detection, 
zero-weight  cycle  detection,  maximum  profit  to  cost  ratio,  and  mirror  of  a  graph. 
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FIGURE  4.4.  Classes  in  the  graph.analysis  package. 
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FIGURE  4.5.  Classes  in  the  graph.analysis  package  (Cont.). 
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4.2.9  Graph  Analyzers 


FIGURE  4.6.  Classes  in  the  graph.analysis.analyzer  package. 
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4.2.10  Strategies 


FIGURE  4.7.  Classes  in  the  graph.analysis. strategy. 
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FIGURE  4.8.  Classes  in  the  graph. analysis. strategy  (Cont.). 
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FIGURE  4.9.  Classes  in  the  graph. analysis. strategy  (Cont.). 
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4.2.11  Cached  Strategies  vs.  Non-Cached  Strategies 

To  facilitate  demand-driven  and  incremental  recomputation  of  analyzers,  the  results  of  those  strat¬ 
egies  that  extend  the  ptolemy.graph.analysis.CachedStrategy  class  are  cached  internally,  and  are 
recomputed  only  when  the  graph  has  changed  since  the  last  request  for  the  strategy  result. 

The  graph  changes  tracked  by  an  analyzer  are  restricted  to  changes  in  the  graph  topology  (the  set 
of  nodes  and  edges).  For  example,  changes  to  edge/node  weights  that  may  affect  the  result  of  an  analy¬ 
sis  are  not  tracked,  since  analyzers  have  no  specific  knowledge  of  weights.  In  such  cases,  it  is  the 
responsibility  of  the  client  (or  derived  analyzer  class)  to  invalidate  the  cached  result  when  changes  to 
graph  weights  or  other  non-topology  information  render  the  cached  result  obsolete.  For  this  reason, 
some  caution  is  generally  required  when  using  analyzers  whose  results  depend  on  more  than  just  the 
graph  topology.  In  these  cases  the  client  should  check  for  data  consistency.  Refer  to  the  class  API  for 
more  details. 
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4.2.12  Graph  Schedules 


-_firingElementClass  :  Class 
-JterationCount :  int  =  1 
-  scheduleVersion  :  long 
#_parent :  ScheduleElement 


+ScheduleElement() 

+firinglterator()  :  Iterator 

+firingElementClass() :  Class 

+firingElementlterator()  :  Iterator 

+getlterationCount() :  int 

+setlterationCount(count :  int) :  void 

+setParent(parent :  ScheduleElement) :  void 

+toParenthesisString(nameMap  :  Map) :  String 

+toParenthesisString(nameMap  :  Map,  delimiter :  String)  :  String 

#_incrementVersion() :  void 

#_getVersion() :  long 


-_firingElementClass  :  Class 
I#  schedule  :  List 


ptolemy.graph.sched. Schedule 


+Schedule() 

+Shedule(firingElementClass  :  Class) 
+add(element :  ScheduleElement)  :  void 
+add(index  :  int,  element :  ScheduleElement) :  void 
+appearanceCount(firingElement :  Object)  :  int 
+firings(firingElement :  Object)  :  List 
+get(index  :  int)  :  ScheduleElement 
+lexicalOrder() :  List 
+maxAppearanceCount() :  int 
+iterator() :  Iterator 

+remove(index  :  int) :  ScheduleElement 
+size()  :  int 
+toString() :  String 


-_firingElement :  Object 


ptolemy.graph.sched.  Firing 


+Firing() 

+Firing(firingElement :  Object) 
+Firing(firingElementClass  :  Class) 
+getFiringElement() :  Object 
+setFiringElement(firingElement :  Object) 
+toString()  :  String 


'  «lnterface»  1 

«lnterface» 

'  ptolemy.graph. analysis. analyzer.GraphAnalyzer  1 

1 

ptolemy.sched. ScheduleAnalyzer 

I - 1 

1  1 

+schedule() :  Schedule 

I  I 

j  ptolemy. graph. analysis. Analysis  | 


I— 


ptolemy.sched.ScheduleAnalysis 


+ScheduleAnalysis(analyzer :  ScheduleAnalyzer) 
+schedule() :  Schedule 


FIGURE  4.10.  Classes  in  the  graph. sched  package. 
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4.2.13  Graph  Exceptions 

The  GraphException  class  is  the  base  class  for  exceptions  for  graph  errors.  This  is  also  an  instance 
of  RuntimeException. 

GraphElementException  is  an  exception  for  graph  element  access  errors.  The  errors  are  usually 
due  to  access  of  nonexistent  elements  or  invalid  element  types. 

GraphWeightException  is  an  exception  for  graph  element  weight  access  errors.  The  errors  are  usu¬ 
ally  due  to  access  of  nonexistent  weights  or  invalid  weight  types. 

GraphConstructionException  is  an  exception  for  graph  structure  construction  errors.  Some  exam¬ 
ples  of  the  errors  are:  addition  of  elements  already  existing,  and  addition  of  an  edge  where  a  connec¬ 
tion  between  the  ending  nodes  is  built. 

GraphStateException  is  thrown  when  a  functional  computation  is  executed  on  a  graph  with  incor¬ 
rect  states.  Graphs  with  incorrect  states  lead  to  invalid  results  or  even  making  functions  incomputable. 
Our  design  should  make  it  impossible  for  this  exception  to  ever  occur,  so  occurrence  is  a  bug. 

GraphTopologyException  is  an  exception  for  operations  on  invalid  graph  topology. 

GraphActionException  is  an  exception  for  invalid  actions  executed  on  graphs.  The  actions  refer  to 
operations  taking  a  graph  as  an  argument  rather  than  that  in  modifying  the  graph  structure.  For  the  lat¬ 
ter  case,  GraphConstructionException  should  be  thrown. 
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GraphWeightException 


+GraphWeightException(message  :  String) 

+GraphWeightException(weight :  Object,  element :  Element,  graph  :  Graph,  message  :  String) 
-_argumentsToString(weight :  Object,  element :  Element,  graph  :  Graph,  message  :  String) :  String 


GraphElementException 


+GraphElementException(message  :  String) 

+GraphElementException(element :  Element,  graph  :  Graph,  message  :  String) 
+checkEdge(edge  :  Edge,  graph  :  Graph) 

+checkNode(node  :  Node,  graph  :  Graph) 

-_argumentsToString(element :  Element,  graph  :  Graph,  message  :  String) :  String 


GraphException 


+GraphException() 

+GraphException(message  :  String) 

+elementDump(element :  Element,  graph  :  Graph) :  String 
+graphDump(graph  :  Graph) :  String 
+weightDump(weight :  Object) :  String 

#_elementDump(element :  Object,  graph  :  Graph,  elementDescriptor :  String) :  String 


Jjava.Iang.RuntimeException  j 


GraphConstruction  Exception 


|+GraphConstructionException(message  :  String)  | 


GraphStateException 


ptolemy.kernel.util.lllegalActionException 


+GraphStateException(message :  String) 


GraphActionException 


+GraphActionException(message  :  String) 


GraphTopologyException 


+GraphTopologyException(message  :  String) 


FIGURE  4.11.  Classes  in  the  graph  exceptions. 
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4.2.14  Directed  Acyclic  Graphs  and  CPO 

The  DirectedAcyclicGraph  class  shown  in  Figure  4.4.2  further  restricts  DirectedGraph  by  not 
allowing  cycles.  For  performance  reasons,  this  requirement  is  not  checked  when  edges  are  added  to  the 
graph,  but  is  checked  when  any  of  the  graph  operations  is  invoked.  An  exception  is  thrown  if  the  graph 
is  found  to  be  cyclic. 

The  CPO  interface  defines  the  common  operations  on  CPOs.  The  mathematical  definition  of  these 
operations  can  be  found  in  [24].  Informal  definitions  are  given  in  the  class  documentation.  This  inter¬ 
face  is  implemented  by  the  class  DirectedAcyclicGraph. 

Since  most  of  the  CPO  operations  involve  the  comparison  of  two  elements,  and  comparison  can  be 
done  in  constant  time  once  the  transitive  closure  is  available,  DirectedAcyclicGraph  makes  heavy  use 
of  the  transitive  closure.  Also,  since  most  of  the  operations  on  a  CPO  have  a  dual  operation,  such  as 
least  upper  bound  and  greatest  lower  bound,  least  element  and  greatest  element,  etc.,  the  code  for  the 
dual  operations  can  be  shared  if  the  order  relation  on  the  CPO  is  reversed.  This  is  done  by  transposing 
the  transitive  closure  matrix. 


FIGURE  4.12.  CPO  related  classes  in  the  core  of  the  graph  package. 
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4.2.15  Inequality  Terms,  Inequalities,  and  the  Inequality  Solver 

The  InequalityTerm  interface  and  Inequality  and  InequalitySolver  classes  support  the  construction 
of  a  set  of  inequality  constraints  over  a  CPO  and  the  identification  of  a  member  of  the  CPO  that  satis¬ 
fies  the  constraints.  A  constraint  is  an  inequality  defined  over  a  CPO,  which  can  involve  constants, 
variables,  and  functions.  As  an  example,  the  following  is  a  set  of  constraints  over  the  4-point  CPO  in 
Figure  4.13: 
a  <w 
P  <xacx 
a  <  P 

where  a  and  P  are  variables,  and  a  denotes  greatest  lower  bound.  One  solution  to  this  set  of  constraints 
is  a  =  P  =  x. 

An  inequality  term  is  either  a  constant,  a  variable,  or  a  function  over  a  CPO.  The  InequalityTerm 
interface  defines  the  operations  on  a  term.  If  a  term  consists  of  a  single  variable,  the  value  of  the  vari¬ 
able  can  be  set  to  a  specific  element  of  the  underlying  CPO.  The  isSettable()  method  queries  whether 
the  value  of  a  term  can  be  set.  It  returns  true  if  the  term  is  a  variable,  and  false  if  it  is  a  constant  or  a 
function.  The  setValue()  method  is  used  to  set  the  value  for  variable  terms.  The  getValue()  method 
returns  the  current  value  of  the  term,  which  is  a  constant  if  the  term  consists  of  a  single  constant,  the 
current  value  of  a  variable  if  the  term  consists  of  a  single  variable,  or  the  evaluation  of  a  function  based 
on  the  current  value  of  the  variables  if  the  term  is  a  function.  The  getVariables()  method  returns  all  the 
variables  contained  in  a  term.  This  method  is  used  by  the  inequality  solver. 

The  Inequality  class  contains  two  InequalityTerms,  a  lesser  term  and  the  greater  term.  The  isSatis- 
fied()  method  tests  whether  the  inequality  is  satisfied  over  the  specified  CPO  based  on  the  current 
value  of  the  variables.  It  returns  true  if  the  inequality  is  satisfied,  and  false  otherwise. 

The  InequalitySolver  class  implements  an  algorithm  to  determine  satisfiability  of  a  set  of  inequal¬ 
ity  constraints  and  to  find  the  solution  to  the  constraints  if  they  are  satisfiable.  This  algorithm  is 
described  in  [107].  It  is  basically  an  iterative  procedure  to  update  the  value  of  variables  until  all  the 
constraints  are  satisfied,  or  until  conflicts  among  the  constraints  are  found.  Some  limitations  on  the 
type  of  constraints  apply  for  the  algorithm  to  work.  The  method  addlnequality()  adds  an  inequality  to 
the  set  of  constraints.  Two  methods  solveLeast()  and  solveGreatest()  can  be  used  to  solve  the  con¬ 
straints.  The  former  tries  to  find  the  least  solution,  while  the  latter  attempts  to  find  the  greatest  solu¬ 
tion.  If  a  solution  is  found,  these  methods  return  true  and  the  current  value  of  the  variables  is  the 
solution.  The  method  unsatisfiedlnequalities()  returns  an  enumeration  of  the  inequalities  that  are  not 
satisfied  based  on  the  current  value  of  the  variables.  It  can  be  used  after  solveLeast()  or  solveGreatest() 
return  false  to  find  out  which  inequalities  cannot  be  satisfied  after  the  algorithm  runs.  The  bottom  Vari- 
ables()  and  topVariables()  methods  return  enumerations  of  the  variables  whose  current  values  are  the 
bottom  or  the  top  element  of  the  CPO. 
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4.3  Example  Use 

4.3.1  Generating  A  Schedule  for  a  Composite  Actor 

Figure  4.14  shows  an  example  of  using  a  topological  sort  to  generate  a  firing  schedule  for  a  Com- 
positeActor  of  the  actor  package.  The  connectivity  information  among  the  Actors  within  the  composite 
is  translated  into  a  directed  acyclic  graph,  with  each  node  of  the  graph  represented  by  an  Actor.  The 
schedule  is  stored  in  an  array,  where  each  element  of  the  array  is  a  reference  to  an  Actor. 

4.3.2  Forming  and  Solving  Constraints  over  a  CPO 

The  code  in  Figure  4.15  implements  the  Inequality  Term  interface  and  models  the  variable  term. 
The  values  of  these  terms  are  Strings.  Inequalities  can  be  formed  using  these  two  classes.  As  another 
example,  the  class  in  Figure  4.16  constructs  the  4-point  CPO  of  Figure  4.13,  forms  a  set  of  constraints 
with  three  inequalities,  and  solves  for  both  the  least  and  greatest  solutions.  The  inequalities  are  a  <  w; 
b  <  a;  b  <  z,  where  w  and  z  are  constants  in  Figure  4.13,  and  a  and  b  are  type  variables  (for  example 
representing  the  type  of  a  port  or  parameter). 
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Object []  generateSchedule (CompositeActor  composite)  { 

DirectedAcyclicGraph  dag  =  new  DirectedAcyclicGraph () ; 

//  Add  all  the  actors  contained  in  the  composite  to  the  graph. 
Iterator  actors  =  composite. deepEntityList (). iterator () ; 
while  (actors .hasNext () )  { 

Actor  actor  =  (Actor) actors .next ()  ; 
dag.addNodeWeight (actor) ; 

) 

//  Add  all  the  connection  in  the  composite  as  graph  edges, 
actors  =  composite . deepEntityList (). iterator () ; 
while  (actors .hasNext  () )  { 

Actor  lowerActor  =  (Actor) actors .next  () ; 

//  Find  all  the  actors  "higher"  than  the  current  one. 
Iterator  outPorts  =  lowerActor . outputPortList (). iterator  () ; 
while  (outPorts .hasNext () )  { 

IOPort  outputPort  =  (IOPort) outPorts .next () ; 

Iterator  inPorts  = 

outputPort . deepConnectedlnPortList () . iterator () ; 
while  (inPorts .hasNext () )  { 

IOPort  inputPort  =  (IOPort) inPorts .next () ; 

Actor  higherActor  =  (Actor) inputPort . getContainer  () ; 
if  (dag. containsNodeWeight (higherActor) )  { 
dag.addEdge (lowerActor,  higherActor) ; 

} 

} 

} 

} 

return  dag . topologicalSort  () ; 


FIGURE  4. 14.  An  example  of  using  a  topological  sort  to  generate  a  firing  schedule  for  a  CompositeActor  of 
the  actor  package. 
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import  ptolemy. graph. *; 
import  ptolemy. kernel .util. *; 

//  A  constant  InequalityTerm  with  a  String  Value, 
class  Constant  implements  InequalityTerm  { 

//  Construct  a  constant  term  with  the  specified  String  value, 
public  Constant (String  value)  { 

_value  =  value; 

} 


//  Return  the  String  associated  with  this  term, 
public  Object  getAssociatedObject ()  { 
return  _value; 

} 


//  Return  the  constant  String  value  of  this  term, 
public  Object  getValueO  { 
return  _value; 

} 


//  Constant  terms  do  not  contain  variables,  so  return  an  array  of  size  zero, 
public  InequalityTerm [ ]  getVariables ()  { 
return  new  InequalityTerm[0] ; 

} 


//  Initialize  the  value  of  this  term  to  the  specified  CPO  element, 
public  void  initialize (Object  object)  throws  IllegalActionException  { 
throw  new  IllegalActionException ("Constant  inequality  term  cannot  be 
+  "initialized.  Its  value  is  set  in  the  constructor."); 


//  Constant  terms  are  not  settable, 
public  boolean  isSettableO  { 
return  false; 

} 


//  Check  whether  the  current  value  of  this  term  is  acceptable, 
public  boolean  isValueAcceptable ( )  { 

return  _value  !=  null;  //  Any  non-null  string  value  is  acceptable. 

} 


//  Throw  an  Exception  on  an  attempt  to  change  this  constant, 
public  void  setValue (Object  e)  throws  IllegalActionException  { 
throw  new  IllegalActionException ("This  term  is  a  constant."); 

} 


//  the  String  value  of  this  term, 
private  String  _value  =  null; 


FIGURE  4.15.  A  class  that  implements  the  InequalityTerm  interface  and  models  the  constant  term. 
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import  ptolemy . graph . *; 

//  An  example  of  forming  and  solving  inequality  constraints, 
public  class  TestSolver  { 

public  static  void  main (String [ ]  argv)  { 

//  construct  the  4-point  CPO  in  figure  2.3. 

CPO  cpo  =  constructCPO () ; 

//  create  inequality  terms  for  constants  w,  z  and 
//  variables  a,  b. 

InequalityTerm  tw  =  new  Constant ("w") ; 

InequalityTerm  tz  =  new  Constant ("z") ; 

InequalityTerm  ta  =  new  Variable (); 

InequalityTerm  tb  =  new  Variable (); 

//  form  inequalities:  a<=w;  b<=a;  b<=z . 

Inequality  iaw  =  new  Inequality (ta,  tw) ; 

Inequality  iba  =  new  Inequality (tb,  ta) ; 

Inequality  ibz  =  new  Inequality (tb,  tz); 

//  create  the  solver  and  add  the  inequalities. 

InequalitySolver  solver  =  new  InequalitySolver (cpo) ; 
solver . addlnequality (iaw) ; 
solver . addlnequality (iba) ; 
solver . addlnequality (ibz) ; 

//  solve  for  the  least  solution 
boolean  satisfied  =  solver . solveLeast () ; 

//  The  output  should  be: 

//  satisfied=true,  least  solution:  a=z  b=z 

System. out .println ("satisf ied="  +  satisfied  +  ",  least  solution:" 

+  "  a="  +  ta.getValue ()  +  "  b="  +  tb.getValue ()) ; 

//  solve  for  the  greatest  solution 
satisfied  =  solver. solveGreatest () ; 

//  The  output  should  be: 

//  satisf ied=true,  greatest  solution:  a=w  b=z 

System. out. println ("satisfied="  +  satisfied  +  ",  greatest  solution: 
+  "  a="  +  ta.getValue ()  +  "  b="  +  tb.getValue ()) ; 


public  static  CPO  constructCPO ( )  { 

DirectedAcyclicGraph  cpo  =  new  DirectedAcyclicGraph ( ) ; 

cpo . addNodeWeight ("w") ; 
cpo . addNodeWeight ("x") ; 
cpo . addNodeWeight ("y") ; 
cpo . addNodeWeight ("z") ; 

cpo . addEdge ( "x" ,  "w" ) ; 
cpo . addEdge ( "y" ,  "w" ) ; 
cpo . addEdge ( " z " ,  "x" ) ; 
cpo . addEdge ("z",  "y") ; 

return  cpo; 

) 

) 


FIGURE  4.16.  An  example  that  constructs  the  4-point  CPO  of  Figure  4.4.13. 
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5.1  Introduction 

The  computation  infrastructure  provided  by  the  basic  actor  classes  is  not  statically  typed,  i.e.,  the 
IOPorts  on  actors  do  not  specify  the  type  of  tokens  that  can  pass  through  them.  This  can  be  changed  by 
giving  each  IOPort  a  type.  One  of  the  reasons  for  static  typing  is  to  increase  the  level  of  safety,  which 
means  reducing  the  number  of  untrapped  errors  [21]. 

In  a  computation  environment,  two  kinds  of  execution  errors  can  occur,  trapped  errors  and 
untrapped  errors.  Trapped  errors  cause  the  computation  to  stop  immediately,  but  untrapped  errors  may 
go  unnoticed  (for  a  while)  and  later  cause  arbitrary  behavior.  Examples  of  untrapped  errors  in  a  general 
purpose  language  are  jumping  to  the  wrong  address,  or  accessing  data  past  the  end  of  an  array.  In 
Ptolemy  II,  the  underlying  language  Java  is  quite  safe,  so  errors  rarely,  if  ever,  cause  arbitrary  behav¬ 
ior.1  However,  errors  can  certainly  go  unnoticed  for  an  arbitrary  amount  of  time.  As  an  example,  figure 
5.1  shows  an  imaginary  application  where  a  signal  from  a  source  is  downsampled,  then  fed  to  a  fast 
Fourier  transform  (FFT)  actor,  and  the  transform  result  is  displayed  by  an  actor.  Suppose  the  FFT  actor 
can  accept  ComplexToken  at  its  input,  and  the  behavior  of  the  DownSample  actor  is  to  just  pass  every 
second  token  through  regardless  of  its  type.  If  the  Source  actor  sends  instances  of  ComplexToken, 
everything  works  fine.  But  if,  due  to  an  error,  the  Source  actor  sends  out  a  StringToken,  then  the 
StringToken  will  pass  through  the  sampler  unnoticed.  In  a  more  complex  system,  the  time  lag  between 
when  a  token  of  the  wrong  type  is  sent  by  an  actor  and  the  detection  of  the  wrong  type  may  be  arbi¬ 
trarily  long. 

1.  Synchronization  errors  in  multi-thread  applications  are  not  considered  here. 
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In  languages  without  static  typing,  such  as  Lisp  and  the  scripting  language  Tel,  safety  is  achieved 
by  writing  defensive  code.  When  safe  execution  is  required,  code  must  check  manually  at  run-time 
whether  the  types  of  values  are  correct.  In  Ptolemy  II,  if  we  imitated  this  approach,  we  would  have  to 
require  actors  to  check  the  type  of  the  received  tokens  before  using  them.  For  example,  the  FFT  actor 
would  have  to  verify  that  the  every  received  token  is  an  instance  of  ComplexToken,  or  convert  it  to 
ComplexToken  if  possible.  This  approach  places  the  burden  of  type  checking  on  actor  developers,  dis¬ 
tracting  them  from  their  development  effort.  It  also  relies  on  a  policy  that  cannot  be  enforced  by  the 
system.  Furthermore,  since  type  checking  is  postponed  to  the  last  possible  moment,  the  system  does 
not  have  fail-fast  behavior,  so  a  system  may  generate  an  error  message  long  after  the  error  occurs,  as 
illustrated  in  figure  5.1.  To  make  matters  worse,  an  actor  may  receive  tokens  from  multiple  sources.  If 
a  token  with  an  incompatible  type  is  received,  it  can  be  hard  to  identify  the  original  source  of  the  token. 
These  potential  problems  can  make  debugging  models  unnecessarily  difficult. 

To  address  this  and  other  issues  discussed  later,  Ptolemy  II  includes  static  type  checking.  This 
approach  is  a  significant  extension  of  the  simple  type  mechanism  in  Ptolemy  Classic.  In  general-pur¬ 
pose  statically-typed  languages,  such  as  C++  and  Java,  static  type  checking  done  by  the  compiler  can 
find  many  potential  program  errors.  However,  execution  of  a  model  in  Ptolemy  II  is  more  similar  to  an 
interpreted  execution,  and  does  not  generally  involve  compilation.  Nonetheless,  static  type  checking  of 
the  model  can  still  be  used  to  detect  modeling  errors  before  actors  fire.  In  figure  5.1,  if  the  Source  actor 
declares  that  its  output  port  type  is  string,  meaning  that  it  will  send  out  StringTokens  upon  firing,  the 
static  type  checker  will  identify  this  type  conflict  in  the  topology. 

In  Ptolemy  II,  because  actors  may  contain  arbitrary  Java  code,  static  typing  alone  is  not  enough  to 
ensure  type  safety  at  run-time.  For  example,  even  if  the  above  Source  actor  declares  its  output  type  to 
be  complex,  it  may  still  attempt  to  send  out  a  StringToken  at  run-time;  for  instance,  the  Source  actor 
might  contain  a  bug  that  incorrectly  declares  the  type  of  a  port.  Hence  run-time  type  checking  is  still 
necessary  for  the  Ptolemy  framework  to  guarantee  that  all  actors  receive  tokens  of  an  expected  type. 
Fortunately,  with  the  help  of  static  type  checking,  run-time  type  checks  can  be  performed  automati¬ 
cally  when  a  token  is  sent  out  from  a  port.  The  run-time  type  checker  simply  compares  the  type  of  a 
produced  token  against  the  type  of  the  output  port.  This  way,  a  type  error  is  detected  at  the  earliest  pos¬ 
sible  time  and  less  reliance  on  correct  actor  specifications  is  needed  to  ensure  type  safety.  Addition¬ 
ally,  actors  can  safely  cast  received  tokens  to  the  type  of  the  input  port  without  manually  checking  the 
type,  making  actor  development  easier. 

We  have  found  that  type  checking  and  type  safety  conversions  can  greatly  increase  our  confidence 
in  making  use  of  reusable  components.  However,  static  typing  does  have  some  drawbacks.  For 
instance,  it  often  requires  actor  authors  to  explicitly  declare  what  type(s)  of  data  are  allowed,  making  it 
more  difficult  to  develop  components.  Ousterhout  [124]  also  argues  that  static  typing  discourages  the 
reuse  of  existing  components. 
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FIGURE  5.1.  An  imaginary  Ptolemy  II  application 
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“Typing  encourages  programmers  to  create  a  variety  of  incompatible  interfaces, 
each  interface  requires  objects  of  specific  type  and  the  compiler  prevents  any  other 
types  of  objects  from  being  used  with  the  interface,  even  if  that  would  be  useful”. 

In  this  chapter  we  will  concentrate  on  two  mechanisms  for  increasing  the  reusability  of  actors  in  the 
presence  of  static  type  checking.  The  first  mechanism,  called  automatic  type  conversion,  allows  a  com¬ 
ponent  to  receive  multiple  data  types  by  automatically  converting  them  to  a  single  data  type.  A  second 
mechanism,  called  type  resolution  or  type  inference,  allows  constructing  data-polymorphic  actors. 
Such  actors  operate  in  a  similar  way  on  different  data  types.  This  chapter  will  describe  how  these 
mechanisms  are  integrated  into  the  Ptolemy  II  static  type  checking  framework. 

One  mechanism  that  enables  polymorphism  in  Ptolemy  II  is  automatic  type  conversion.  The 
allowed  automatic  data  type  conversions  are  represented  in  figure  5.2,  called  the  type  lattice.  In  this 
diagram,  a  conversion  from  one  type  to  another  is  allowed  if  the  first  type  appears  below  the  second 
type  in  the  diagram.  This  relationship  implies  a  partial  ordering  of  types,  so  we  might  say  that  a  con¬ 
version  is  allowed  if  the  first  type  is  less  than  or  equal  to  the  second  type. 

Automatic  conversions  primarily  occur  during  data  transfer  from  one  port  to  another.  When  a  data 
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FIGURE  5.2.  The  Type  Lattice 
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token  is  received,  it  is  automatically  converted  to  the  type  of  the  input  port  receiving  it.  Along  with  the 
run-time  type  checking  of  sent  data  described  earlier,  this  conversion  implies  that  across  every  connec¬ 
tion  from  an  output  port  to  an  input,  the  type  of  the  output  must  be  the  same  as  or  lower  than  the  type 
of  the  input.  This  requirement  is  called  the  type  compatibility  rule.  For  example,  an  output  port  with 
type  int  can  be  connected  to  an  input  port  with  type  double,  and  tokens  sent  by  the  output  port  will  be 
converted  to  type  double  before  being  received.  On  the  other  hand,  a  double  to  int  connection  will  gen¬ 
erate  a  type  error  during  static  type  checking,  since  no  conversion  is  possible.  These  conversions  are 
performed  transparently  by  the  Ptolemy  II  system  (actors  are  not  aware  it).  Automatic  conversions  are 
also  often  performed  in  the  data  package  when  type-polymorphic  operations  are  applied  to  values  of 
different  types. 

The  type  lattice  was  constructed  based  on  a  principle  of  lossless  conversion.  A  conversion  is 
allowed  automatically  as  long  as  important  information  about  value  of  data  tokens  are  not  lost.  Such 
conversions  are  referred  to  as  widening  conversions  in  Java.  For  instance,  converting  a  32-bit  signed 
integer  to  a  64-bit  IEEE  double  precision  floating  point  number  is  allowed  since  every  integer  can  be 
represented  exactly  as  a  floating  point  number.  On  the  other  hand,  data  type  conversions  that  lose 
information  are  not  included  in  the  type  lattice  of  automatic  conversions.  In  fact,  the  concentration  on 
lossless  conversions  is  somewhat  arbitrary,  but  we  find  that  it  is  relatively  easy  to  use,  since  it  mini¬ 
mizes  unintentional  loss  of  numerical  precision. 

While  automatic  type  conversion  allows  an  actor  to  receive  data  of  different  types,  the  operation 
performed  by  the  actor  is  always  performed  on  the  same  type  of  data,  determined  by  the  type  of  the 
ports.  However,  there  are  cases  where  an  actor  operates  on  tokens  without  regard  for  the  actual  types  of 
the  tokens.  For  example,  the  DownSample  in  figure  5.1  does  not  care  about  the  type  of  token  going 
through  it;  it  works  with  any  type  of  token.  In  general,  the  types  on  some  or  all  of  the  ports  of  a  poly¬ 
morphic  actor  are  not  rigidly  defined  to  specific  types  when  the  actor  is  written,  so  the  actor  can  inter¬ 
act  with  other  actors  having  different  types,  increasing  reusability. 

In  Ptolemy  Classic,  the  ports  on  type-polymorphic  actors  whose  types  are  not  specified  are  said  to 
have  ANYTYPE.  ANYTYPE  ports  were  allowed  to  be  connected  to  ports  of  any  other  type.  However, 
in  the  presence  of  such  ports  means  that  type  safety  cannot  be  ensured.  Instead,  Ptolemy  II  allows  ports 
to  have  undeclared  type,  suggesting  that  the  type  of  those  ports  has  not  been  determined  but  cannot  be 
assigned  arbitrarily.  Instead  of  being  given  as  constants,  the  acceptable  types  on  polymorphic  actors 
are  described  by  a  set  of  type  constraints.  The  type  checker  checks  the  applicability  of  a  type-polymor¬ 
phic  actor  in  a  model  by  finding  specific  types  for  ports  that  satisfy  the  type  constraints.  This  process  is 
called  type  resolution  or  type  inference,  and  the  specific  types  are  called  the  resolved  types.  Assuming 
the  type  constraints  of  actors  are  consistent  with  the  actor  implementation,  this  technique  can  ensure 
the  type  safety  of  actor  connections.  Type  constraints  and  the  type  resolution  algorithm  are  described 
more  completely  in  the  next  section. 

In  addition  to  ports,  the  parameters  which  are  used  to  configure  actors  are  also  typed  objects.  By 
defining  a  uniform  interface  for  setting  up  type  constraints,  Ptolemy  II  supports  type  constraints 
between  parameters  and  ports,  as  well  as  between  ports.  This  extends  the  range  of  type  checking  to 
allow  parameters  with  arbitrary  type,  such  as  those  that  determine  the  values  produced  by  source 
actors. 

In  Ptolemy  II,  typing  does  apply  some  restrictions  on  the  interaction  of  actors.  Particularly,  actors 
cannot  be  interconnected  arbitrarily  if  the  type  compatibility  rule  is  violated.  However,  such  models 
rarely  make  any  sense,  so  the  benefit  of  typing  should  far  outweigh  the  inconvenience  caused  by  this 
restriction.  On  the  other  hand,  type  declarations  and  type  constraints  help  to  clarify  the  interface  of 
actors  and  makes  them  more  manageable.  Static  typing  also  provide  an  opportunity  for  model  compiler 
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and  circuit  synthesis  tools  to  generate  type  specialized  code,  when  a  Ptolemy  system  is  synthesized  to 
hardware,  type  information  can  be  used  for  efficient  synthesis.  If  the  type  checker  asserts  that  a  certain 
polymorphic  actor  will  only  receive  IntTokens,  then  only  hardware  dealing  with  integers  needs  to  be 
synthesized. 

To  summarize,  Ptolemy  II  takes  an  approach  of  static  typing  coupled  with  run-time  type  checking. 
Lossless  data  type  conversions  during  data  transfer  are  automatically  executed.  Polymorphic  actors  are 
supported  through  type  resolution. 

5.2  Formulation 

5.2.1  Type  Constraints 

In  a  Ptolemy  II  topology,  the  type  compatibility  rule  imposes  a  type  constraint  across  every  con¬ 
nection  from  an  output  port  to  an  input  port.  It  requires  that  the  type  of  the  output  port,  outType,  be  the 
same  as  the  type  of  the  input  port,  inType,  or  less  than  inType  under  the  type  lattice.  This  can  be  written 
as  an  inequality: 

outType  <  inType  (5) 

This  constraint  guarantees  that  there  is  an  allowed  automatic  conversion  that  can  be  performed  during 
data  transfer.  If  both  the  outType  and  inType  are  declared,  the  static  type  checker  simply  checks 
whether  this  inequality  is  satisfied,  and  reports  a  type  conflict  if  it  is  not. 

In  addition  to  the  above  constraint  imposed  by  the  topology,  actors  may  also  impose  constraints. 
This  happens  when  one  or  both  of  the  outType  and  inType  is  undeclared,  in  which  case  the  actor  con¬ 
taining  the  undeclared  port  needs  to  describe  the  acceptable  types  through  type  constraints.  All  the  type 
constraints  in  Ptolemy  II  are  described  in  the  form  of  inequalities  like  the  one  in  (5).  If  a  port  or  param¬ 
eter  has  a  declared  type,  its  type  appears  as  a  constant  in  the  inequalities.  On  the  other  hand,  if  a  port  or 
parameter  has  an  undeclared  type,  its  type  is  represented  in  the  inequalities  by  a  variable,  called  a  type 
variable.  The  value  of  type  variables  are  allowed  to  range  over  the  elements  of  the  type  lattice.  The 
type  resolution  algorithm  resolves  the  values  of  type  variables  subject  to  the  constraints  of  the  model 
and  the  actors.  If  no  solution  exists,  a  type  conflict  error  will  be  reported.  As  an  example  of  the  ine¬ 
quality  constraints,  consider  figure  5.3. 

The  port  of  actor  A1  has  declared  type  int  and  the  ports  of  A3  and  A4  have  declared  type  double. 
The  types  of  the  ports  of  A2,  on  the  other  hand,  have  been  left  undeclared.  If  the  type  variables  of  the 
undeclared  types  are  a,  [I,  and  y,  then  the  type  constraints  from  the  topology  are: 


FIGURE  5.3.  A  topology  with  types. 
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int  <  a 
double  <  P 
y  <  double 

Now,  assume  A2  is  a  polymorphic  adder,  capable  of  doing  addition  for  integer,  double,  and  complex 
numbers,  and  the  requirement  is  that  it  does  not  lose  precision  during  the  operation.  Then  the  type  con¬ 
straints  for  the  adder  can  be  written  as: 
a  <  y 

P  -  y 

y  <  complex 

The  first  two  inequalities  constrain  the  output  precision  to  be  no  less  than  input,  the  last  one 
requires  that  the  data  on  the  adder  ports  can  be  converted  to  complex  losslessly.  These  six  inequalities 
form  the  complete  set  of  constraints  and  are  used  by  the  type  resolution  algorithm  to  solve  for  a,  |3,  and 
y.  Hence,  the  problem  has  been  converted  from  type  resolution  into  a  problem  of  solving  a  set  of  ine¬ 
qualities.  An  efficient  algorithm  is  available  to  solve  constraints  in  finite  lattices  [130],  which  is 
described  in  the  appendix  through  an  example.  This  algorithm  finds  the  set  of  most  specific  types  for 
the  undeclared  types  in  the  topology  that  satisfy  the  constraints,  if  they  exist. 

This  inequality  formulation  is  inspired  by  the  type  inference  algorithm  in  ML  [110].  There,  equali¬ 
ties  are  used  to  represent  type  constraints.  In  Ptolemy  II,  the  lossless  type  conversion  hierarchy  natu¬ 
rally  implies  inequality  relation  among  the  types.  In  ML,  the  type  constraints  are  generated  from 
program  constructs.  In  a  heterogeneous  graphical  programming  environment  like  Ptolemy  II,  the  sys¬ 
tem  does  not  have  enough  information  about  the  function  of  the  actors,  so  actors  must  specify  type 
information  either  by  declaring  port  types,  or  by  providing  type  constraints  to  describe  the  acceptable 
types  of  undeclared  ports. 

As  mentioned  earlier,  the  static  type  checker  flags  a  type  conflict  error  if  the  type  compatibility 
rule  is  violated  on  a  certain  connection.  There  are  other  kind  of  type  conflicts  indicated  by  one  of  the 
following: 

•  The  set  of  type  constraints  are  not  satisfiable. 

•  Some  type  variables  are  resolved  to  unknown. 

•  Some  type  variables  are  resolved  to  an  abstract  type,  such  as  Numerical  in  the  type  hierarchy. 

The  first  case  can  happen,  for  example,  if  the  port  of  actor  A1  in  figure  5.3  has  declared  type  com¬ 
plex.  The  second  case  can  happen  if  an  actor  does  not  specify  any  type  constraints  on  an  undeclared 
output  port.  This  is  due  to  the  nature  of  the  type  resolution  algorithm  where  it  assigns  all  the  unde¬ 
clared  types  to  unknown  at  the  beginning.  If  the  type  constraints  do  not  restrict  a  type  variable  to  be 
greater  than  unknown,  it  will  stay  at  unknown  after  resolution.  The  third  case  is  considered  a  conflict 
since  an  abstract  type  does  not  correspond  to  an  instantiable  token  class. 

5.2.2  Run-time  Type  Checking  and  Lossless  Type  Conversion 

The  declared  type  is  a  contract  between  an  actor  and  the  Ptolemy  II  system.  If  an  actor  declares  an 
output  port  to  have  a  certain  type,  it  asserts  that  it  will  only  send  out  tokens  whose  types  are  less  than 
or  equal  to  that  type.  If  an  actor  declares  an  input  port  to  have  a  certain  type,  it  requires  the  system  to 
only  send  tokens  that  are  instances  of  the  class  of  that  type  to  that  input  port.  Run-time  type  checking 
enforces  this  contract,  regardless  of  whether  individual  actors  respect  it.  When  a  token  is  sent  out  from 
an  output  port,  the  run-time  type  checker  queries  its  type  and  compares  the  type  with  the  declared  type 
of  the  output  port.  If  the  type  of  the  token  is  not  less  than  or  equal  to  the  declared  type,  a  run-time  type 
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error  will  be  generated. 

As  discussed  before,  type  conversion  is  performed  automatically  when  a  token  sent  to  an  input 
port  has  a  type  less  than  the  type  of  the  input  port.  This  conversion  enables  an  actor  to  safely  cast  a 
received  token  to  the  type  of  the  port.  On  the  other  hand,  when  an  actor  sends  out  tokens,  the  tokens 
being  sent  do  not  have  to  have  the  exact  declared  output  port  type.  Any  type  that  is  less  than  the 
declared  type  is  acceptable.  For  example,  if  an  output  port  has  declared  type  double,  the  actor  can  send 
IntToken  from  that  port.  As  can  be  seen,  the  automatic  type  conversion  simplifies  the  input/output  han¬ 
dling  of  the  actors. 

Note  that  even  with  the  convenience  provided  by  the  type  conversion,  actors  should  still  declare 
the  input  types  to  be  the  most  general  that  they  can  handle  and  the  output  types  to  be  the  most  specific 
type  that  includes  all  tokens  they  will  send.  This  maximizes  their  applications.  In  the  previous  exam¬ 
ple,  if  the  actor  only  sends  out  IntToken,  it  should  declare  the  output  type  to  be  int  to  allow  the  port  to 
be  connected  with  an  input  with  type  int. 

If  an  actor  has  ports  with  undeclared  types,  its  type  constraints  can  be  viewed  as  both  a  require¬ 
ment  and  an  assertion  from  the  actor.  The  actor  requires  the  resolved  types  to  satisfy  the  constraints. 
Once  the  resolved  types  are  found,  they  serve  exactly  the  same  role  as  declared  types  at  run  time.  The 
the  type  checking  and  type  conversion  system  guarantees  the  type  of  tokens  received  by  an  actor,  and 
the  actor  guarantees  the  types  of  tokens  sent  by  the  actor.  These  assumptions  and  guarantees  are  sum¬ 
marized  for  all  possible  types  by  the  type  constraints  of  the  actor. 

5.3  Structured  Types 

Structured  types  include  those  tokens  which  aggregate  other  tokens  of  arbitrary  type,  such  as  array 
and  record  types.  As  described  in  the  Data  Package  chapter,  an  ArrayToken  contains  an  array  of 
tokens,  and  the  element  tokens  can  have  arbitrary  type.  For  example,  an  ArrayToken  can  contain  an 
array  of  StringTokens,  or  an  array  of  Array  Tokens.  In  the  latter  case,  the  ArrayToken  can  be  regarded 
as  a  two  dimensional  array.  RecordToken  contains  a  set  of  labeled  tokens,  like  the  structure  in  the  C 
language.  It  is  useful  for  grouping  multiple  pieces  of  related  information  together.  In  the  type  lattice  in 
figure  5.2,  record  types  are  incomparable  with  all  the  base  types,  except  the  top  and  the  bottom  ele¬ 
ments  of  the  lattice.  Array  types  are  a  bit  more  complex  because  any  type  is  less  than  an  array  of  that 
type  in  the  type  lattice.  This  is  hinted  at  in  the  figure  with  the  disconnected  lines  at  the  bottom  of  the 
array  type.  Note  that  the  lattice  nodes  Array  and  Record  actually  represent  an  infinite  number  of  types, 
so  the  type  lattice  becomes  infinite. 

The  order  relation  between  two  array  types  is  that  type  [B )  (the  type  of  arrays  containing  elements 
of  type  B)  is  less  than  type  {A}  if  B  is  less  than  A,  or  if  A  is  an  array  of  elements  of  type  B.  This  is  a 
recursive  definition  if  the  element  types  A  and  B  are  themselves  structured  types.  For  example,  {int}  < 
{double},  {{int}}  <  {{double}} ,  where  {{int}}  is  an  array  of  array.  Moreover,  {int}  <  {{double}}. 

The  order  relation  between  two  record  types  follows  the  standard  depth  subtyping  and  width  sub¬ 
typing  relations  [27],  In  depth  subtyping,  a  record  type  C  is  a  subtype  of  a  record  type  D  if  the  type  of 
some  fields  of  C  is  a  subtype  of  the  corresponding  fields  in  D.  In  width  subtyping,  a  record  with  more 
fields  is  a  subtype  of  a  record  with  less  fields.  For  example,  we  have: 

{x  =  string,  y  =  int}  <  {x  =  string,  y  =  double} 

{x  =  string,  y  =  double,  z  =  int}  <  {x  =  string,  y  =  double} 
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Here,  we  use  the  {label  =  type,  label  =  type,  ...}  syntax  to  denote  record  types.  Notice  that  the 
width  subtyping  rule  implies  a  type  conversion  which  loses  information,  discarding  the  extra  fields  of 
a  record. 

Another  structured  type  is  the  union  type.  It  allows  the  user  to  create  a  token  that  can  hold  data  of 
various  types,  but  only  one  at  a  time.  This  is  like  the  union  construct  in  C.  The  union  type  is  also  called 
variant  types  in  the  type  system  literature.  The  width  subtyping  relation  for  union  type  is  the  opposite 
to  that  of  the  record  type.  That  is,  a  shorter  union  is  a  subtype  of  a  longer  one.  This  means  that  there  are 
an  infinite  number  of  types  from  a  particular  union  type  to  the  top  of  the  type  lattice,  so  the  conver¬ 
gence  of  the  type  resolution  algorithm  is  not  immediately  obvious.  We  are  currently  addressing  this 
issue  and  working  on  the  implementation  of  the  union  type  in  Ptolemy  II. 

One  final  structured  type  is  the  type  of  function  closures.  Each  function  closure  is  represented  by 
an  instance  of  the  FunctionToken  class.  Function  closures  take  several  arguments  and  return  a  single 
value.  The  type  system  supports  function  types  where  the  arguments  have  declared  types,  and  the 
return  type  is  known.  Function  types  are  related  in  a  way  that  is  contravariant  (oppositely  related) 
between  inputs  and  outputs.  Namely,  if  function(x:z>7t,  y.int)  int  is  a  function  that  of  two  integer  argu¬ 
ments  that  returns  an  integer,  then 

function(x:z'77t,  y.int)  int  <  function(x:mt,  y.int)  double 

function(x://7t,  y.double)  int  <  function(x:mt,  y.int)  int 

The  contravariant  notion  here  is  easiest  to  think  about  in  terms  of  the  automatic  type  conversion  of 
one  function  into  another.  A  function  that  returns  int  can  be  converted  into  a  function  that  returns  dou¬ 
ble  by  adding  a  conversion  of  the  returned  value  from  int  to  double.  On  the  other  hand,  a  function  that 
takes  an  int  cannot  be  converted  into  a  function  that  takes  a  double,  since  that  would  mean  that  the 
function  is  suddenly  able  to  accept  double  arguments  when  it  could  not  before,  and  there  is  no  auto¬ 
matic  conversion  from  double  to  int.  Functions  that  are  lower  in  the  type  lattice  assume  less  about  their 
inputs  and  guarantee  more  about  their  outputs.  Note  particularly  that  the  names  of  arguments  do  not 
affect  the  relation  between  two  function  types,  since  argument  binding  is  by  the  order  of  arguments 
only.  Additionally,  functions  with  different  numbers  of  arguments  are  considered  incomparable.  Even¬ 
tually,  we  intend  to  provide  an  actor  token  as  well,  which  would  have  both  contravariance  of  the  types 
of  input  and  output  ports  as  well  as  allowing  width  subtyping,  similarly  to  records.  The  presence  of 
function  types  that  can  be  used  as  any  other  token  results  in  what  is  commonly  termed  a  higher-order 
type  system. 

Type  constraints  can  be  specified  between  the  element  type  of  a  structured  type  and  the  type  of  a 
Ptolemy  object.  For  example,  a  type  constraint  can  specify  that  the  type  of  a  port  is  no  less  than  the 
type  of  the  elements  of  an  ArrayToken. 

5.3.1  Setting  Up  Type  Constraints 

In  most  cases,  type  constraints  can  be  set  up  easily  through  the  methods  in  the  Typeable  interface. 
The  setTypeAtMost()  method  is  usually  invoked  on  input  ports  to  declare  a  requirement  that  input 
tokens  must  satisfy,  while  the  setTypeAtFeast()  method  is  usually  invoked  on  output  ports  to  declare  a 
guarantee  of  the  type  of  the  output.  The  setTypeEquals()  method  can  also  be  used  to  force  the  type  of 
typeable  objects  to  a  particular  data  type.  As  an  example,  the  constraint  that  the  type  of  an  input  port 
can  be  no  greater  than  double  might  be  declared  as: 

inputPort . setTypeAtMost (BaseType . DOUBLE)  ; 
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and  a  constraint  that  the  type  of  an  output  port  can  be  no  less  than  the  type  of  a  parameter: 

outputPort . setTypeAtLeast (parameter) ; 

This  latter  type  constraint  is  commonly  seen  when  parameter  values  are  used  to  compute  values  pro¬ 
duced  from  an  output  port.  To  declare  that  a  parameter  is  an  array  of  doubles,  use 

parameter . setTypeEquals (new  ArrayType (BaseType . DOUBLE) ) ; 

Notice  that  the  argument  to  setTypeAtMost()  and  setTypeEquals()  is  a  Type,  whereas  the  argument  to 
setTypeAtLeast()  is  a  Typeable  object.  This  reflects  the  common  usages,  where  setTypeAtLeast()  is 
declaring  a  dependency  on  externally  provided  types,  whereas  setTypeAtMost()  and  setTypeEquals() 
are  declaring  constraints  on  externally  defined  types. 

More  complex  type  constraints  arise  from  structured  types,  such  as  arrays  and  records.  The  previ¬ 
ous  example  showed  how  to  declare  that  a  parameter  or  a  port  has  a  particular  array  type.  A  more  flex¬ 
ible  parameter  might  be  able  to  contain  an  array  of  any  type.  This  is  expresses  as  follows, 

parameter . setTypeAtLeast (ArrayType .ARRAY  BOTTOM) ; 

In  a  more  elaborate  example,  we  might  constrain  the  type  of  an  output  port  to  be  no  less  than  the  ele¬ 
ment  type  of  the  array  contained  by  a  parameter  (or  an  input  port): 

outputPort . setTypeAtLeast (ArrayType . arrayOf (parameter) )  ; 

To  declare  that  an  output  port  has  a  type  at  least  that  of  the  elements  of  input  array  (or  parameter),  use 

outputPort . setTypeAtLeast (ArrayType . elementType ( inputPort) )  ; 

The  above  code  implicitly  constrains  the  input  port  to  have  an  array  type,  but  the  constrain  the  element 
types  of  that  array. 

The  above  kinds  of  constraints  appear  in  source  actors  such  as  Clock  and  Pulse,  and  ArrayToEle- 
ments  and  ElementsToArray. 

Another  common  constraint  is  that  an  input  port  of  an  actor  receives  a  RecordToken  with  uncon¬ 
strained  fields.  This  constraint  can  be  declared  using  the  following  code: 

String []  labels  =  new  String[0]; 

Type [ ]  types  =  new  Type[0]; 

RecordType  declaredType  =  new  RecordType ( labels ,  types); 
inputPort . setTypeAtMost (declaredType) ; 

Two  of  the  types,  matrix  and  scalar,  are  union  types.  This  means  that  an  instance  of  this  type  can 
be  any  of  the  types  immediately  below  them  in  the  lattice.  An  actor  may,  for  example,  declare  that  an 
input  port  must  be  of  type  no  greater  than  scalar  by  using  the  following  code, 

inputPort . setTypeAtMost (BaseType . SCALAR) ; 
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In  this  case,  inputs  of  any  type  immediately  below  scalar  in  the  type  lattice  will  not  be  converted, 
except  that  the  type  of  the  input  tokens  will  be  reported  as  scalar.  This  is  useful,  for  example,  in  actors 
that  need  to  compare  tokens,  such  as  the  Limiter  actor.  The  fire()  method  of  that  actor  contains  the 
code 


if  ( input . hasToken ( 0 ) )  { 

ScalarToken  in  =  (ScalarToken)  input . get  (0 ) ; 
if  ( (in . isLessThan ( (ScalarToken)  bottom. getToken ()) ) 
.booleanValue ( ) )  { 

output . send ( 0  ,  bottom. getToken ( ) ) ; 

}  else  if  ( (in. isGreaterThan ( (ScalarToken)  top . getToken ()) ) 
. booleanValue () )  { 

output . send ( 0 ,  top . getToken ()) ; 

}  else  { 

output . send ( 0 ,  in ) ; 

1 

1 


This  code  relies  on  the  fact  that  input  port  in  and  parameter  bottom  have  been  declared  to  be  at  most 
scalar  type,  and  that  ScalarToken  is  a  base  class  for  every  token  with  type  immediately  below  scalar. 
It  then  uses  comparison  methods  defined  in  the  ScalarToken  class. 

Internally,  the  class  Inequality  in  the  graph  package  is  used  to  represent  type  constraints.  This  class 
references  two  objects  implementing  the  Inequality  Term  interface,  one  for  each  side  of  the  inequality. 
The  InequalityTerm  interface  is  implemented  by  inner  classes  of  TypedlOPort,  Variable,  Array  Type, 
and  RecordType,  to  encapsulate  the  type  of  the  port,  the  variable,  and  the  element  type  of  structured 
types.  For  some  more  elaborate  type  constraints,  the  actor  programmer  can  use  these  classes  directly. 
Specifically,  in  some  actors,  simple  constraints  between  variables  are  not  capable  of  representing  the 
type  constraints  between  ports  and  parameters.  In  such  cases,  monotonic  functions  can  be  used  to  spec¬ 
ify  more  complex  type  constraints.  That  is,  constraints  in  the  form  f(a)  <  p  are  admitted,  where  f(a)  is 
a  monotonic  function  of  a,  and  P  can  be  a  constant  or  a  variable.  An  example  of  this  appears  in  the 
Absolute  Value  actor  in  the  actor  library.  Here,  one  of  the  type  constraints  is:  If  the  input  type  is  not 
complex,  the  output  type  is  the  same  as  the  input  type,  otherwise,  the  output  type  is  double.  This  con¬ 
straint  can  be  expressed  as  f(inputType)  <  outputType,  where 

f(inputType)  =  inputType,  if  inputType  ^  complex 

f(inputType)  =  double,  if  inputType  =  complex. 

This  function  is  implemented  by  an  inner  class  of  Absolute  Value  that  implements  InequalityTerm. 
The  evaluation  is  done  in  the  getValue()  method  of  InequalityTerm  as: 

public  Object  getValueO  { 

//  _port  is  the  input  port 
Type  inputType  =  _port . getType ( ) ; 

return  inputType  ==  BaseType . COMPLEX  ?  BaseType . DOUBLE  :  inputType; 

1 

Directly  implementing  the  InequalityTerm  interface  is  actually  rather  complex,  and  is  imple¬ 
mented  in  the  same  pattern  for  all  monotonic  function  constraints.  The  MonotonicFunction  base  class, 
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which  implements  the  uninteresting  parts  of  the  InequalityTerm  interface,  allows  actors  to  easily 
implement  new  monotonic  function  constraints.  Lastly,  if  the  methods  in  Typeable  are  not  sufficient 
for  specifying  complicated  constraints,  or  the  default  implementation  of  the  typeConstraints()  method 
in  the  TypedAtomicActor  is  not  appropriate,  this  method  can  be  overridden,  but  this  is  rarely  needed. 

5.3.2  Array  Lengths 

Between  Ptolemy  II  6.0  and  Ptolemy  II  7.0,  the  way  array  lengths  are  handled  changed. 

The  Array  Type  class  now  represents  the  length  of  arrays.  New  methods  were  added: 

boolean  hasKnownLength ( ) 
int  length  ( ) 

The  length()  method  throws  a  RuntimeException  when  length()  is  invoked  on  an  ArrayType  with 
hasKnownLength()  ==  false.  Existing  ArrayType  instances  (created  using  the  Array Type(Type)  con¬ 
structor)  have  unknown  length.  A  new  constructor  Array Type(Type,  int)  creates  array  types  with  a 
known  length.  Generally  speaking,  array  types  with  known  length  are  incomparable  with  array  types 
with  different  lengths,  and  can  be  converted  to  an  array  type  with  unknown  length  and  compatible  ele¬ 
ment  type.  Scalars  are  convertible  to  array  types  with  length  1 .  Getting  the  code  to  do  this  right  was 
significantly  more  complex  than  inferring  sizes  of  Fix-point  types  because: 

1.  The  FixType  modifications  were  easily  factored  since  any  FixType  with  a  known  length  is  less 

than  the  single  FixType  with  an  unknown  length.  ArrayType  could  not  be  factored  this  way 

because  of  the  more  complex  type  relations. 

2.  FixType  doesn't  have  a  contained  type  variable. 

Array  Types  now  have  type  construction  functions:  array  Type(int)  and  array  Type(  int,  4)  represent 
the  types  that  you  might  expect. 

Unfortunately,  this  means  that  there  is  a  significant  backward-compatibility  issue.  Previously,  if 
you  wanted  to  force  an  arbitrary  integer  array  type,  you  used  {int},  which  is  really  an  array  with  one 
element.  This  now  has  the  type  array Type(int,  1),  which  is  more  specific  than  you  probably  want. 

As  a  result,  in  almost  any  case  where  the  old  style  is  used  in  a  model  to  declare  the  type  of  a  port  in 
a  model,  e.g.  {int},  it  should  be  replaced  with  an  array  Type  declaration,  e.g.  arrayType(int,  7),  or  array- 
Type(int).  If  this  is  not  done,  such  models  will  most  likely  have  a  type  error  related  to  an  array  of 
length  one. 

The  existing  models  have  been  updated  using  the  new  description  of  an  array  type  with  an 
unknown  length. 

Note  that  array Type(int)  returns  an  instance  of  the  special  class  UnsizedArray Token,  whose  only 
purpose  is  to  have  an  unknown  array  size.  Regular  array  tokens  always  have  a  known  length. 

Note  also  that  array  Type(unknown)  is  no  longer  the  GFB  of  all  of  the  array  Types.  The  GFB  is 
now  represented  by  BaseType.ARRAY  BOTTOM  (which  is  not  an  instance  of  ArrayType).  This 
required  moving  farther  along  the  path  of  decoupling  type  constraints  on  array  element  types  from  the 
type  objects  themselves.  TypeableElementTypeTerm  can  now  refer  to  the  element  type  of  a  typeable 
which  may  never  resolve  to  a  valid  array  type  (resulting  in  an  unsatisfied  inequality  term). 
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5.4  Implementation 

5.4.1  Implementation  Classes 

All  the  classes  for  representing  the  types  and  the  type  lattice  are  under  the  data.type  package,  as 
shown  in  figure  5.4.  The  Type  interface  defines  the  basic  operations  on  a  type.  BaseType  contains  a 


«lnterface» 

Type 

pmrrhv 

Type  Lattice 

-  lattice  :  TheTvDeLattice 

+convert(t :  Token) :  Token 
+equals(type  :  Type) :  boolean 
+isCompatible(type  :  Type) :  boolean 
+isConstant() :  boolean 
+islnstantialble() :  boolean 
+isSubstitutionlnstance(type  :  Type) :  boolean 

Cl  cl  1  Cl  ly 

0..1 

+compare(token1  :  Token,  token2  :  Token) :  int 

+compare(token  :  Token,  type  :  Type) :  int 

+compare(tvpe  :  Type,  token  :  Token) :  int 

+comDare(tvoe1  :  Tvoe.  tvDe2  :  Tvoe) :  int 

+Iattice0  :  araoh.CPO 

5 


BaseType 

+BOOLEAN  :  BaseType 

+BOOLEAN  MATRIX  :  BaseTvDe 

+COMPLEX  :  BaseType 

+COMPLEX  MATRIX  :  BaseType 

+DOUBLE  :  BaseType 

+DOUBLE  MATRIX  :  BaseType 

+FIX  :  BaseTvDe 

+FIX  MATRIX  :  BaseType 

+GENEF1AL  :  BaseType 

+INT  :  BaseType 

+INT  MATRIX :  BaseType 

+LONG  :  BaseTvoe 

+LONG  MATRIX  :  BaseType 

+MATRIX  :  BaseType 

+NUMERICAL  :  BaseType 

+OBJECT  :  BaseType 

+SCALAR  :  BaseTvoe 

+STRING  :  BaseType 

+UNKNOWN  :  BaseType 

+UNSIGNED  BYTE  :  BaseType 

-_name  :  String 

+forClassName(className  :  String) :  Type 

+forName(name  :  Strina) :  Tvoe 

+getTokenClass() :  Class 

«lnterface» 

InequalityTerm 


. 7C" . 

I 

TypeConstant 


-_type  :  Type 

+TypeConstant(type  :  Type) 


«lnterface» 

Typeable 


+getType() :  Type 
+getTypeTerm() :  InequalityTerm 
+setTypeAtLeast(lesser :  Typeable) 
+setTypeAtLeast(typeTerm :  InequalityTerm) 
+setTypeAtMost(type :  Type) 
+setTypeEquals(type  :  Type) 
+setTypeSameAs(equal :  Typeable) 
+typeConstraintList() :  List 


FIGURE  5.4.  Classes  in  the  data.type  package. 
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type-safe  enumeration  of  primitive  types.  For  example,  unknown,  the  bottom  element  of  the  type  lat¬ 
tice  which  can  be  resolved  to  any  type  is  represented  by  the  field  BaseType.UNKNOWN.  Array  Type 
and  RecordType  are  derived  from  an  abstract  class  StructuredType.  Each  type  has  a  convert()  method 
to  convert  a  token  lower  in  the  type  lattice  to  one  of  its  type.  For  base  types,  this  method  just  calls  the 
same  method  in  the  corresponding  tokens.  For  structured  types,  the  conversion  is  done  within  the  con¬ 
crete  structured  type  classes. 

The  Typeable  interface  defines  a  set  of  methods  to  set  type  constraints  between  typed  objects.  It  is 
implemented  by  the  Variable  class  in  the  data.expr  package  and  the  TypedlOPort  class  in  the  actor 
package.  The  TypeConstant  class  encapsulates  a  constant  type.  It  implements  the  InequalityTerm 
interface  and  can  be  used  to  set  up  type  constraints  between  a  typed  object  and  a  constant  type. 

In  the  actor  package,  the  Actor  interface,  the  AtomicActor,  CompositeActor,  IOPort  and  IORela- 
tion  classes  are  extended  with  TypedActor,  TypedAtomicActor,  TypedCompositeActor,  TypedlOPort 
and  TypedlORelation,  respectively,  as  shown  in  figure  5.5.  The  container  for  TypedlOPort  must  be  a 
ComponentEntity  implementing  the  TypedActor  interface,  namely,  TypedAtomicActor  or  TypedCom¬ 
positeActor.  The  TypedlORelation  class  is  only  able  to  connect  instances  of  the  TypedlOPort.  Type¬ 
dlOPort  has  a  declared  type  and  a  resolved  type.  Declaring  a  type  of  BaseType.UNKNOWN  allows 
the  type  system  to  infer  the  resolved  type  of  a  port.  If  a  port  has  a  declared  type  that  is  not  Base¬ 
Type.UNKNOWN,  the  resolved  type  will  be  the  same  as  the  declared  type. 

5.4.2  Type  Checking  and  Type  Resolution 

Static  type  checking  and  type  resolution  are  performed  by  the  resolveTypes()  method  of  the 
TypedCompositeActor  class.  This  method  finds  all  connections  within  the  composite  by  first  finding 
the  output  ports  on  deep  contained  entities,  and  then  finding  input  ports  deeply  connected  to  those  out¬ 
put  ports.  Transparent  ports  are  ignored  for  type  checking.  For  each  connection,  if  the  types  on  both 
ends  are  declared,  static  type  checking  is  performed  using  the  type  compatibility  rule.  If  the  model 
contains  other  opaque  TypedCompositeActors,  this  method  recursively  calls  the 
_checkDeclaredTypes()  method  of  the  contained  actors  to  perform  type  checking  on  the  entire  hierar¬ 
chy.  Hence,  if  resolveTypes()  is  called  with  the  top  level  TypedCompositeActor,  type  checking  is  per¬ 
formed  through  out  the  hierarchy. 

If  a  type  conflict  is  detected,  i.e.,  if  the  declared  type  at  the  source  end  of  a  connection  is  greater 
than  or  incomparable  with  the  type  at  the  destination  end  of  the  connection,  then  the  ports  at  both  ends 
of  the  connection  are  recorded  and  will  be  returned  in  a  List  at  the  end  of  type  checking.  Note  that  type 
checking  does  not  stop  after  detecting  the  first  type  conflict,  so  the  returned  List  contains  all  the  ports 
that  have  type  conflicts.  This  behavior  is  similar  to  a  regular  compiler,  where  compilation  will  gener¬ 
ally  continue  after  detecting  errors  in  the  source  code. 

The  TypedActor  interface  declares  a  typeConstraintList()  method,  which  returns  the  type  con¬ 
straints  of  this  actor.  The  TypedAtomicActor  base  class  provides  a  default  implementation  of  this 
method,  which  requires  that  the  type  of  any  input  port  with  undeclared  type  must  be  less  than  or  equal 
to  the  type  of  any  undeclared  output  port.  Ports  with  declared  types  are  not  included  in  the  default  con¬ 
straints.  If  all  of  an  actor’s  ports  have  declared  types,  no  constraints  are  generated.  This  default  is 
appropriate  for  many  type-polymorphic  actors  such  as  the  Commutator  actor,  the  Multiplexer  actor, 
and  the  DownSample  actor  in  figure  5.1.  In  addition,  the  typeConstraintList()  method  also  collects  all 
the  constraints  from  the  contained  Typeable  objects,  which  are  TypedlOPorts  and  Variables. 

The  typeConstraintList()  method  in  TypedCompositeActor  collects  all  the  constraints  for  a  model, 
including  the  constraints  for  actors  and  the  constraints  for  connections  between  actors.  It  works  in  a 


Heterogeneous  Concurrent  Modeling  and  Design 


127 


Type  System 


similar  fashion  as  the  _checkDeclaredTypes()  method,  by  recursively  traversing  the  containment  hier¬ 
archy.  It  also  scans  all  the  connections  and  forms  additional  type  constraints  on  connections  involving 
undeclared  types.  As  with  _checkDeclaredTypes(),  if  this  method  is  called  on  the  top  level  container, 
all  the  type  constraints  within  the  entire  model  are  returned. 

The  Manager  class  has  a  resolveTypes()  method  that  performs  both  type  checking  and  resolution. 
It  uses  the  InequalitySolver  class  in  the  graph  package  to  solve  the  constraints.  If  type  conflicts  are 


FIGURE  5.5.  Classes  in  the  actor  package  that  support  type  checking. 
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detected  during  type  checking  or  after  type  resolution,  this  method  throws  a  TypeConflictException. 
This  exception  contains  a  list  of  inequalities  where  type  conflicts  occurred.  The  resolveTypes()  method 
is  invoked  by  the  Manager  of  a  model  between  the  preinitialize()  and  initialize()  phases,  and  after  any 
mutations  are  processed. 

Run-time  type  checking  is  performed  in  the  send()  method  of  TypedlOPort.  The  checking  is  sim¬ 
ply  a  comparison  of  the  type  of  the  token  being  sent  with  the  resolved  type  of  the  port.  If  the  type  of  the 
token  is  less  than  or  equal  to  the  resolved  type,  type  checking  is  passed,  otherwise,  an  IllegalActionEx- 
ception  is  thrown. 

Type  conversion,  if  needed,  is  also  done  in  the  sendQ  method.  The  type  of  the  destination  port  is 
the  resolved  type  of  the  port  containing  the  receivers  that  the  token  is  sent  to.  If  the  token  does  not  have 
that  type,  the  convert()  method  on  that  type  is  called  to  perform  the  conversion. 

5.4.3  Some  Implementation  Details 

The  implementation  of  the  structured  types  is  more  involved  than  the  base  types.  This  is  because 
the  base  types  are  atomic,  but  structured  types  that  contain  type  variables  are  mutable  entities.  For 
example,  the  declared  type  of  a  port  can  be  {unknown},  meaning  that  it  is  an  array  of  undefined  ele¬ 
ment  type.  After  type  resolution,  that  type  may  be  updated  to  {double}.  Types  that  are  mutable  are 
variable  types.  The  isConstant()  method  in  Type  determines  if  a  type  contains  a  type  variable.  Type 
variables  are  represented  by  a  type  initialized  to  BaseType.UNKNOWN. 

When  a  typed  object  is  cloned,  if  its  type  is  a  variable  structured  type,  that  type  must  be  cloned 
because  the  original  and  the  cloned  Typeable  objects  may  have  different  types  in  the  future.  Similarly, 
when  constructing  structured  types  with  variable  structured  types  as  element  types,  the  element  types 
must  be  cloned.  However,  constant  structured  types  do  not  need  to  be  cloned.  This  means  that  an 
instance  of  a  constant  StructuredType  can  be  shared  by  many  objects,  but  an  instance  of  a  variable 
StructuredType  can  only  have  one  user.  To  ensure  this,  structured  types  are  always  cloned  when  ports 
and  parameters  that  contain  them  are  cloned.  This  incurs  some  redundant  cloning,  but  the  overhead  is 
small. 

A  variable  type  can  be  updated  to  another  type,  provided  that  the  new  type  is  compatible  with  the 
variable  type.  For  example,  if  a  type  variable  a  can  be  updated  to  any  type,  then  {a}  can  be  updated  to 
{int}.  However,  {a}  cannot  be  updated  to  int.  If  a  variable  type  can  be  updated  to  a  new  type,  the  new 
type  is  called  a  substitution  instance  of  the  variable  type.  This  term  is  borrowed  from  type  literature. 
Formally,  a  type  is  a  substitution  instance  of  a  variable  type  if  the  former  can  be  obtained  by  substitut¬ 
ing  the  type  variables  of  the  latter  to  another  type.  The  method  isSubstitutionInstance()  in  the  Type 
base  class  performs  this  check. 

The  updateType()  method  in  StructuredType  is  used  to  change  the  variable  element  type  of  a  struc¬ 
tured  type.  For  example,  if  the  types  of  two  ports  are  {int}  and  {a}  respectively,  and  a  type  constraint  is 
that  the  second  port  is  no  less  than  the  type  of  the  first,  that  is,  {int}  <  {a},  the  type  resolution  algo¬ 
rithm  will  change  the  resolved  type  of  the  second  port  to  {int}.  This  step  cannot  be  done  by  simply 
changing  the  type  reference  in  the  second  port  to  an  instance  of  {int},  since  type  constraints  may  be  set 
up  between  a  and  other  typed  objects.  Instead,  updateType()  only  changes  the  type  reference  for  a  to 
int. 
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5.5  Examples 

5.5.1  Polymorphic  DownSample 

In  figure  5.1,  if  the  DownSample  is  designed  to  do  downsampling  for  any  kind  of  token,  its  type 
constraint  is  just  sampler  In  <  sampler  Out,  where  sampler  In  and  sampler  Out  are  the  types  of  the  input 
and  output  ports,  respectively.  The  default  type  constraints  work  in  this  case.  Assuming  the  Display 
actor  just  calls  the  toString()  method  of  the  received  tokens  and  displays  the  string  value  in  a  certain 
window,  the  declared  type  of  its  port  would  be  General.  Let  the  declared  types  on  the  ports  of  FFT  be 
complex,  then  the  type  constraints  of  this  simple  application  are: 
sourceOut  <  samplerln 
samplerln  <  samplerOut 
samplerOut  <  complex 
complex  <  General 

Where  sourceOut  represents  the  declared  type  of  the  Source  output.  The  last  constraint  does  not 
involve  a  type  variable,  so  it  is  just  checked  by  the  static  type  checker  and  not  included  in  type  resolu¬ 
tion.  Depending  on  the  value  of  sourceOut,  the  ports  on  the  DownSample  actor  would  be  resolved  to 
different  types.  Some  possibilities  are: 

•  If  sourceOut  =  complex,  the  resolved  types  would  be  samplerln  =  samplerOut  =  complex. 

•  If  sourceOut  =  double,  the  resolved  types  would  be  samplerln  =  samplerOut  =  double.  At  run¬ 
time,  DoubleTokens  sent  out  from  the  Source  will  be  passed  to  the  DownSample  actor  unchanged. 
Before  they  leave  the  Downsample  actor  and  are  sent  to  the  FFT  actor,  they  are  converted  to  Com- 
plexTokens  by  the  system.  The  ComplexToken  output  from  the  FFT  actor  are  instances  of  Token, 
which  corresponds  to  the  General  type,  so  they  are  transferred  to  the  input  of  the  Display  without 
change. 

•  If  sourceOut  =  string,  the  set  of  type  constraints  do  not  have  a  solution,  a  typeConflictException 
will  be  thrown  by  the  static  type  checker. 

5.5.2  Fork  Connection 

Consider  two  simple  topologies  in  figure  5.6.  where  a  single  output  is  connected  to  two  inputs  in 
5.6(a)  and  two  outputs  are  connected  to  a  single  input  in  5.6(b).  Denote  the  types  of  the  ports  by  al,  a2, 


(a)  (b) 


FIGURE  5.6.  Two  simple  topologies  with  types. 
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FIGURE  5.7.  Conversion  between  sequence  and  array. 


double 


a3,  bl.  b2,  b3,  as  indicated  in  the  figure.  Some  possibilities  of  legal  and  illegal  type  assignments  are: 

•  In  5.6(a),  if  al  =  int,  a2  =  double,  a3  =  complex,  then  the  topology  is  well  typed.  At  run-time,  the 
IntToken  sent  out  from  actor  Al  will  be  converted  to  DoubleToken  before  transferred  to  A2,  and 
converted  to  ComplexToken  before  transferred  to  A3.  This  shows  that  multiple  ports  with  differ¬ 
ent  types  can  be  interconnected  as  long  as  the  type  compatibility  rule  is  obeyed. 

•  In  5.6(b),  if  bl  =  int,  bl  =  double,  and  b3  is  undeclared,  then  the  the  resolved  type  for  b3  will  be 
double.  If  bl  =  int  and  b2  =  boolean,  the  resolved  type  for  b3  will  be  string  since  it  is  the  lowest 
element  in  the  type  hierarchy  that  is  higher  than  both  int  and  boolean.  In  this  case,  if  the  actor  B3 
has  some  type  constraints  that  require  b3  to  be  less  than  string,  then  type  resolution  is  not  possible, 
and  a  type  conflict  will  be  signaled. 

5.6  Actors  Constructing  Tokens  with  Structured  Types 

The  SDF  domain  contains  two  actors  that  perform  conversion  between  a  sequence  of  tokens  and 
an  ArrayToken.  Type  constraints  in  these  actors  ensure  that  the  type  of  the  array  element  is  the  same  as 
the  type  of  the  sequence  tokens.  When  two  SequenceToArray  actors  are  cascaded,  the  output  of  the 
second  actor  will  be  an  array  of  array.  Cascading  ArrayToSequence  with  SequenceToArray  restores 
the  sequence.  In  these  actors,  the  arrayLength  parameter  determines  the  size  of  the  produced  or  con¬ 
sumed  array,  and  also  determines  the  number  of  tokens  produced  or  consumed  in  each  firing.  If  the 
ArrayToken  received  by  ArrayToSequence  does  not  have  specified  length  and  the  enforceArrayLength 
parameter  is  true,  an  exception  will  be  thrown. 

The  actor.lib  package  contains  two  actors  that  assemble  and  disassemble  RecordTokens:  Recor- 
dAssembler  and  RecordDisassembler.  The  former  assembles  tokens  from  multiple  input  ports  into  a 
RecordToken  and  sends  it  to  the  output  port,  the  latter  does  the  reverse.  The  labels  in  the  RecordToken 
are  the  names  of  the  input  ports.  Type  constraints  ensure  that  the  type  of  the  record  fields  is  the  same  as 
the  type  of  the  corresponding  ports. 
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Appendix  B:  The  Type  Resolution  Algorithm 

The  type  resolution  algorithm  starts  by  assigning  all  the  type  variables  the  bottom  element  of  the 
type  hierarchy,  unknown,  then  repeatedly  updating  the  variables  to  a  greater  element  until  all  the  con¬ 
straints  are  satisfied,  or  when  the  algorithm  finds  that  the  set  of  constraints  are  not  satisfiable.  The 
algorithm  can  determine  satisfiability  for  the  kind  of  inequality  constraints  with  the  greater  term  (the 
right  side  of  the  inequality)  being  a  variable,  or  a  constant.  The  algorithm  allows  the  left  side  of  the 
inequality  to  contain  monotonic  functions  of  the  type  variables,  but  not  the  right  side.  The  first  step  of 
the  algorithm  is  to  divide  the  inequalities  into  two  categories,  Cvar  and  Const.  The  inequalities  in  Cvar 
have  a  variable  on  the  right  side,  and  the  inequalities  in  Const  have  a  constant  on  the  right  side.  In  the 
example  of  figure  5.3,  Cvar  consists  of: 
int  <  a 
double  <  P 
a  <  y 

P  -  Y 

And  Const  consists  of: 

y  <  double 
y  <  complex 

The  repeated  evaluations  are  only  done  on  Cvar.  Const  are  used  as  checks  after  the  iteration  is  fin¬ 
ished,  as  we  will  see  later.  Before  the  iteration,  all  the  variables  are  assigned  the  value  unknown,  and 
Cvar  looks  like: 

int  <  a(unknown) 
double  <  P( unknown ) 
a  {unknown)  <  y( unknown ) 

P( unknown )  <  y( unknown ) 

Where  the  current  value  of  the  variables  are  inside  the  parenthesis  next  to  the  variable. 

At  this  point,  Cvar  is  further  divided  into  two  sets:  those  inequalities  that  are  not  currently  satis¬ 
fied,  and  those  that  are  satisfied: 

Not-satisfied  Satisfied 

int  <  a(unknown)  a(unknown)  <  y( unknown ) 

double  <  P( unknown )  |3( unknown )  <  y( unknown ) 

Now  comes  the  update  step.  The  algorithm  takes  out  an  arbitrary  inequality  from  the  Not-satisfied 
set,  and  forces  it  to  be  satisfied  by  assigning  the  variable  on  the  right  side  the  least  upper  bound  of  the 
values  of  both  sides  of  the  inequality.  Assuming  the  algorithm  takes  out  int  <  a(unknown),  then 

a  =  intvunknown  =  int  (6) 

After  a  is  updated,  all  the  inequalities  in  Cvar  containing  it  are  inspected  and  are  switched  to  either 
the  Satisfied  or  Not-satisfied  set,  if  they  are  not  already  in  the  appropriate  set.  In  this  example,  after 
this  step,  Cvar  is: 

Not-satisfied  Satisfied 

double  <  P( unknown )  int  <  a  (int) 

a  (int)  <  y( unknown )  P( unknown )  <  y( unknown ‘) 

The  update  step  is  repeated  until  all  the  inequalities  in  Cvar  are  satisfied.  In  this  example,  P  and  y 
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will  be  updated  and  the  solution  is: 

a  =  int,  P  =  y  =  double 

Note  that  there  always  exists  a  solution  for  Cvar.  An  obvious  one  is  to  assign  all  the  variables  to 
the  top  element,  General,  although  this  solution  may  not  satisfy  the  constraints  in  Const.  The  above 
iteration  will  find  the  least  solution,  or  the  set  of  most  specific  types. 

After  the  iteration,  the  inequalities  in  Const  are  checked  based  on  the  current  value  of  the  variables. 
If  all  of  them  are  satisfied,  a  solution  to  the  set  of  constraints  is  found. 

This  algorithm  can  be  viewed  as  repeated  evaluation  of  a  monotonic  function,  and  the  solution  is 
the  fixed  point  of  the  function.  Equation  (6)  can  be  viewed  as  a  monotonic  function  applied  to  a  type 
variable.  The  repeated  update  of  all  the  type  variables  can  be  viewed  as  the  evaluation  of  a  monotonic 
function  that  is  the  composition  of  individual  functions  like  (6).  The  evaluation  reaches  a  fixed  point 
when  a  set  of  type  variable  assignments  satisfying  the  constraints  in  Cvar  is  found. 

Rehof  and  Mogensen  [130]  proved  that  the  above  algorithm  is  linear  time  in  the  number  of  occur¬ 
rences  of  symbols  in  the  constraints,  and  gave  an  upper  bound  on  the  number  of  basic  computations.  In 
our  formulation,  the  symbols  are  type  constants  and  type  variables,  and  each  constraint  contains  two 
symbols.  So  the  type  resolution  algorithm  is  linear  in  the  number  of  constraints. 
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6.1  Introduction 

Model  transformation  in  Ptolemy  II  provides  a  mechanism  to  systematically  transform  models  by 
means  of  graph  rewriting  [38].  Each  Ptolemy  model  is  considered  as  a  graph,  with  actors  and  relations 
in  the  model  as  the  nodes  of  the  graph,  and  with  connections  as  the  edges.  Nodes  (and  also  edges  in 
some  cases)  can  be  associated  with  attributes.  A  typical  kind  of  attributes  is  the  type  of  an  actor.  The 
name  of  the  actor  is  another  attribute.  Ptolemy  models  also  has  hierarchy,  created  by  CompositeActors 
that  contain  other  actors  in  it.  Therefore,  the  graphs  that  the  graph  rewriting  facility  must  be  able  to 
handle  are  hierarchical  attributed  graphs.  The  key  idea  of  transformation  is  to  use  a  pattern  graph 
(also  known  as  left-hand  side)  to  match  a  subgraph  in  the  graph  representing  an  input  model,  and  once 
such  a  matched  subgraph  is  found,  to  replace  it  with  a  replacement  graph  (also  known  as  right-hand 
side). 

An  atomic  transformation  rule  defines  an  undivided  transformation  step.  It  is  specified  with  a 
TransformationRule  actor,  which  is  a  special  kind  of  MultiCompositeActor  with  three  tabs  when  the 
user  opens  it.  The  first  tab  provides  a  visual  interface  for  the  user  to  design  a  pattern;  the  second  tab  is 
for  the  design  of  a  replacement;  and  the  third  tab  is  to  specify  the  correspondence  between  entities  in 
the  pattern  and  those  in  the  replacement.  This  interface  with  multiple  tabs  will  be  further  discussed  in 
section  6.2. 
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Because  atomic  transformations  are  themselves  Ptolemy  actors,  it  is  possible  to  compose  multiple 
transformations  in  a  hierarchical  model  using  model(s)  of  computation  chosen.  The  inputs  to  and  out¬ 
puts  from  each  atomic  transformation  actor  consist  of  tokens  containing  models  (represented  internally 
with  graph  structures). 

Model  transformation  has  vast  application  potentials.  Examples  of  applications  include  model 
refactoring  and  model  generation. 

6.2  Atomic  Transformation  Rules 

An  atomic  transfonnation  rule  is  specified  with  a  TransfonnationRule  actor,  which  is  implemented 
in  the  java  class  ptolemy.actor.gt.TransformationRule.  A  special  visual  interface  with  three  tabs  is  pro¬ 
vided  to  the  user,  as  shown  in  figure  6.1.  This  interface  is  due  to  the  triple  graph  grammar  for  specify¬ 
ing  graph  transformation  [140].  In  the  “Pattern”  tab,  Ptolemy  actors  can  be  dragged  from  the  library 
and  be  connected  to  each  other  to  specify  a  pattern.  The  pattern  is  used  to  match  a  subgraph  in  the 
input  model.  In  addition,  a  special  placeholder  called  AtomicActorMatcher  can  also  be  placed  in  this 
tab  to  match  any  arbitrary  actor  in  stead  of  an  actor  with  known  type.  In  the  “Replacement”  tab,  the 
same  editing  area  of  the  window  is  used  to  specify  the  replacement  graph,  which  is  the  graph  to  replace 
the  subgraph  that  the  pattern  matches,  if  any. 

When  an  actor  (or  a  relation)  is  copied  in  the  “Pattern”  tab  and  is  pasted  into  the  “Replacement” 
tab,  an  entry  is  automatically  created  in  the  table  that  is  displayed  when  the  “Correspondence”  tab  is 
chosen.  The  entry  establishes  a  relation  between  an  actor  (or  relation)  in  the  “Pattern”  tab  and  one  in 
the  “Replacement”  tab  (though  in  general  they  may  not  have  the  same  name  and  may  reside  at  differ¬ 
ent  levels  of  the  model  hierarchy). 

The  correspondence  relations  are  important.  Without  any  such  relation,  the  application  of  a  trans¬ 
formation  rule  always  results  in  deleting  the  subgraph  that  the  pattern  matches,  and  adding  the  replace¬ 
ment  graph  back.  This,  however,  disallows  to  connect  the  replacement  graph  with  the  rest  of  the 
model.  The  correspondence  relations  establish  connections  between  the  replacement  and  the  rest  of  the 
model  with  minimal  user  intervention.  An  entity  in  the  pattern  with  a  corresponding  entity  in  the 
replacement  is  not  deleted  at  all.  Instead,  the  object  is  kept  throughout  the  transformation.  If  the  entity 
is  an  actor,  the  attributes  that  it  acquires  previously  remain  after  the  transformation,  as  well  as  its  ports 
and  the  connections  to  those  ports.  If  the  entity  is  a  relation,  its  connections  are  also  preserved. 

For  example,  in  figure  6.1,  A,  B  and  C  are  instances  of  AtomicActorMatcher,  available  from  the 
library  on  the  left  side  of  the  window  when  “Transformation  Editor”  is  chosen  from  the  “New”  menu 
in  Ptolemy’s  “File”  menu.  Ports  are  created  for  them,  and  connections  are  created  by  the  user.  These 


FIGURE  6.1.  Visual  interface  for  the  editing  of  an  atomic  transformation  rule. 
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altogether  represents  a  pattern. 

6.2.1  AtomicActorMatcher 

AtomicActorMatcher  is  highly  configurable.  The  user  can  specify  criteria  for  each  such  actor  so 
that  it  only  matches  certain  kinds  of  actors  in  the  input  model,  such  as  actors  of  a  special  Java  class  or 
actors  with  special  attribute  values. 

Each  criterion  is  implemented  as  a  Java  class  in  the  ptolemy.actor.gt.ingredients. criteria,  subclass¬ 
ing  ptolemy.actor.gt.ingredients.criteria.Criterion.  When  the  user  double-clicks  an  AtomicActor¬ 
Matcher,  such  as  A  in  figure  6.1,  a  window  as  the  one  shown  in  figure  6.2  pops  up,  in  which  criteria 
can  be  added  or  removed.  Elements  of  each  criterion  can  be  specified.  In  figure  6.2,  a  PortCriterion  is 
defined  for  A  in  figure  6. 1.  It  explicitly  declares  that  the  matched  port  must  not  be  an  input  port,  that  it 
must  be  an  output  port,  and  that  it  must  not  accept  more  than  one  output  connection.  We  do  not  check 
the  checkboxes  to  the  left  of  the  items  labeled  “name,”  “type,”  and  “matcherName,”  which  means  we 
are  not  interested  in  those  elements. 

The  criteria  that  have  been  predefined  are  listed  in  the  following  table.  To  understand  the  different 


Table  13:  Criteria 


Criterion  Class 

Element 

Optional 

Explanation 

AttributeCriterion 

name 

no 

Name  of  the  attribute 

type 

yes 

Type  of  the  attribute 

value 

yes 

Value  of  the  attribute 

PortCriterion 

name 

yes 

Name  of  the  port 

type 

yes 

Type  of  the  port 

input 

yes 

Whether  the  port  accepts  input  connections 

output 

yes 

Whether  the  port  accepts  output  connections 

multi 

yes 

Whether  the  port  accepts  multiple  connections 

matcherName 

yes 

Name  of  the  port  created  for  the  AtomicActorMatcher 

SubclassCriterion 

superclass 

no 

Name  of  the  class  that  must  be  a  superclass  or  an  interface 

elements  of  the  predefined  criteria,  we  take  PortCriterion  as  an  example.  All  its  elements  are  optional, 
which  means  the  user  does  not  have  to  specify  any  of  them.  (An  empty  PortCriterion  matches  any 


Normal  text  only 


Regular  expression 


Evaluated  expression 


Do  not  match 


|  Add  [  |  Remove  |  |  Commit  |  [  Apply  |  [  Cancel  | 


FIGURE  6.2.  An  interface  for  editing  criteria  of  an  AtomicActorMatcher. 
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port.)  Once  a  PortCriterion  is  added  to  an  AtomicActorMatcher,  a  port  is  automatically  created.  If  the 
input  or  output  type  of  the  PortCriterion  is  specified,  the  created  port  acquires  the  same  input  or  output 
type. 

The  “name”  element  of  PortCriterion  accepts  a  regular  expression,  as  the  input  box  is  colored  light 
green  background.  (The  background  colors  of  the  input  boxes  are  a  hint  on  what  inputs  are  accepted. 
Explanation  of  the  colors’  meaning  is  at  the  bottom  of  the  criteria  editor  window,  as  in  figure  6.2.) 
With  this  element  specified,  the  PortCriterion  matches  a  port  only  if  the  regular  expression  matches  the 
name  of  that  port. 

A  different  element  about  port  name  is  called  “matcherName.”  This  is  different  from  the  “name” 
element  in  that  it  specifies  the  name  of  the  port  created  for  the  AtomicActorMatcher,  instead  of  the 
name  of  the  port  that  this  PortCriterion  matches.  This  distinction  is  necessary  because  the  port  for  the 
AtomicActorMatcher  must  be  given  a  unique  identifier  as  its  name.  If  “matcherName”  is  not  given  a 
value,  the  name  of  the  created  port  defaults  to  “criterion*,”  where  x  is  the  index  of  the  criterion  in  the 
list  of  criteria. 

Multiple  AtomicActorMatchers  can  be  connected  to  each  other  via  their  ports  as  ordinary  actors  in 
the  Ptolemy  library.  In  the  “Pattern”  tab,  those  connections  contribute  to  the  pattern  matching.  For 
example,  in  figure  6.1,  AtomicActorMatcher  with  name  A  only  matches  an  actor  with  at  least  one  out¬ 
put  port,  which  is  connected  to  a  multi-input  port  of  another  actor  that  C  matches.  In  addition  to  that 
connection,  the  port  of  the  actor  that  C  matches  must  also  have  a  connection  from  a  port  belong  to  yet 
another  actor,  which  B  matches. 

AtomicActorMatcher  are  also  used  in  the  “Replacement”  tab.  However,  the  user  cannot  directly 
create  an  AtomicActorMatcher  in  the  replacement,  because  the  replacement  will  become  a  subgraph  of 
the  resulting  model,  but  AtomicActorMatcher  merely  serves  as  a  placeholder  and  is  not  an  executable 
actor  in  its  own  right.  (Compare  to  the  wildcards  in  regular  expressions.)  The  proper  way  to  use  an 
AtomicActorMatcher  in  the  “Replacement”  tab  is  first  to  copy  an  AtomicActorMatcher  in  the  pattern, 
then  to  paste  it  into  the  replacement.  A  correspondence  relation  is  automatically  created  for  the  two 
AtomicActorMatchers  in  the  “Correspondence”  tab.  This  means  that  the  actor  that  the  AtomicActor¬ 
Matcher  in  the  pattern  matches  is  preserved  in  the  resulting  graph,  so  that  it  has  the  same  attributes  and 
ports  after  transformation.  Connections  to  and  from  its  ports  are  also  preserved  except  those  explicitly 
deleted  by  the  transformation. 

In  the  “Replacement”  tab,  when  the  user  double-clicks  an  AtomicActorMatcher,  an  operation  edi¬ 
tor  is  shown  instead  of  a  criteria  editor  for  an  AtomicActorMatcher  in  the  “Pattern”  tab.  An  example  of 
this  editor  is  shown  in  figure  6.3.  The  following  table  explains  the  elements  of  the  two  kinds  of  opera- 


Class  Elements 


Normal  text  only 


Evaluated  expression 


Do  not  match 


Regular  expression 


[  Add  ]  (  Remove  ]  |  Commit  |  [  Apply  |  [  Cancel  | 


FIGURE  6.3.  An  interface  for  editing  operations  of  an  AtomicActorMatcher. 


138 


Ptolemy  II 


Model  Transformation 


tions.  Each  of  those  operations  is  defined  as  a  class  in  package  ptolemy.actor.gt.ingredients. operations. 

Table  14:  Operations 


Operation 

Element 

Optional 

Explanation 

AttributeOperation 

name 

no 

Name  of  the  attribute 

type 

yes 

Type  of  the  attribute 

value 

no 

Value  of  the  attribute 

RenameOperation 

name 

no 

New  name  for  the  actor 

Each  item  listed  in  the  operation  editor  specifies  an  operation  to  be  performed  on  the  actor  that  the 
corresponding  AtomicActorMatcher  in  the  pattern  matches.  For  example,  an  AttributeOperation  spec¬ 
ifies  an  operation  on  a  single  attribute  of  the  actor.  The  value  of  “name”  element,  which  must  be  an 
identifier,  refers  to  the  name  of  the  affected  attribute.  The  “value”  element  specifies  a  string  to  com¬ 
pute  the  new  value  for  that  attribute.  For  example,  if  the  “value”  element  is  “i+1,”  then  the  value  of  the 
actor’s  attribute  will  be  set  to  “i+1”  after  the  transformation,  where  “i”  is  a  variable  whose  actual  value 
is  retrieved  only  when  the  resulting  model  is  executed.  The  “i”  in  this  case  is  in  the  scope  of  the  modi¬ 
fied  actor.  Elowever,  the  user  can  use  a  special  construct  “$(...)”  to  enforce  transformation-time  evalua¬ 
tion  of  (part  of)  the  string  in  the  “value”  element.  For  example,  if  the  string  is  “$(i+l),”  then  the  value 
of  “i”  is  obtained  when  the  transformation  is  performed.  If  the  affected  actor  has  an  attribute  named 
“i,”  then  the  value  of  that  attribute  is  taken.  If  that  actor  does  not  have  such  an  attribute  but  the  Com- 
positeActor  containing  it  has  attribute  “i,”  then  that  attribute  of  the  CompositeActor  is  taken.  If  “i” 
cannot  be  found  even  when  the  top-level  CompositeActor  is  reached,  an  exception  occurs  at  the  time 
of  transformation.  Once  the  value  of  “i”  is  obtained,  for  example,  2,  then  “i+1”  is  evaluated  and  the 
value  3  is  used  to  substitute  “$(i+l)”  in  the  string. 

The  “type”  element  of  an  AttributeOperation  is  optional.  If  it  is  not  specified  and  the  operation  is 
to  modify  an  existing  attribute,  then  the  type  of  the  attribute  remains  the  same.  If  the  operation  is  to  add 
a  new  attribute,  then  the  “type”  element  is  required,  whose  value  is  usually  “ptolemy.data.expr.Param- 
eter.” 

6.2.2  CompositeActorMatcher 

While  an  AtomicActorMatcher  matches  an  actor,  which  could  be  an  atomic  actor  or  a  composite 
actor  with  its  contents,  a  CompositeActorMatcher  in  the  pattern  matches  a  composite  actor  itself  only. 
Even  though  both  can  be  used  to  match  composite  actors,  there  is  a  subtle  difference  that  needs  to  be 
clarified.  We  consider  a  hierarchical  Ptolemy  model  as  a  tree  structure.  Figure  6.4  provides  an  example 

S~\  A:CompositeActor 

B:CompositeActor  fA  C:CompositeActor 

D:AtomicActor  Cj  Cj  Cj  Cj  G:AtomicActor 
E:  Atomic  Actor  F:  Atomic  A  cot 

FIGURE  6.4.  Tree  view  of  a  model,  whose  non-leaf  nodes  are  CompositeActors. 
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of  such  tree  structures,  in  which  a  CompositeActorMatcher  matches  either  node  A  or  B  or  C  in  the  tree, 
but  an  AtomicActorMatcher  matches  any  subtree,  such  as  the  whole  tree  rooting  at  A  and  the  subtree 
rooting  at  B.  In  addition,  the  latter  also  matches  any  leaf  node. 

The  specialty  of  CompositeActorMatchers  and  AtomicActorMatchers  is  exploited  in  some  trans¬ 
formations.  Since  a  CompositeActorMatcher  matches  a  CompositeActor  excluding  its  contents, 
removing  such  a  placeholder  results  in  moving  the  contents  to  the  upper  level,  instead  of  removing  the 
whole  composite  actor,  as  is  the  effect  of  using  an  AtomicActorMatcher.  For  example,  figure  6.5 
depicts  a  transformation  rule  (with  the  three  tabs  of  the  editor  aligned  side-by-side)  used  to  flatten  the 
hierarchy  in  some  Ptolemy  models.  1  In  the  “Pattern”  tab  there  is  only  a  CompositeActorMatcher  to 
match  any  level  of  hierarchy.  The  CompositeActorMatcher  does  not  have  any  correspondence  in  the 
“Replacement”  tab,  because  in  the  “Correspondence”  tab,  name  “CompositeActorMatcher”  does  not 
appear  under  the  “Pattern  Entity”  column.  Therefore,  as  a  result  of  applying  this  transformation  to  a 
subgraph  of  an  input  model  (in  this  case,  the  subgraph  containing  only  a  CompositeActor),  one  level  of 
hierarchy  is  removed  and  the  contents  inside  are  moved  to  the  outer  level  of  hierarchy. 

If  the  CompositeActorMatcher  in  figure  6.5  were  replaced  with  an  AtomicActorMatcher,  then  an 
application  of  the  transformation  rule  on  a  matched  CompositeActor  in  the  model  would  cause  the 
CompositeActor  along  with  the  contents  in  it  to  be  removed. 

Figure  6.6  shows  an  example  model  to  be  transformed  by  the  transformation  rule  in  figure  6.5. 
This  model  has  two  CompositeActors:  an  implicit  one  at  the  top-level  containing  the  SDF  model  and 
the  other  one  named  “CompositeActor”  within  the  SDF  model.  To  apply  the  transformation,  the  user 
clicks  the  Q  button  in  the  tool  bar  of  the  transformation  rule  editor.  A  dialog  pops  up  for  an  input  file 


Pattern  Replacement  Correspondence 

CompositeActorMatcher 

match 

1— l"La 


Pattern  j  Replacement  Correspondence  Pattern  j  Replacement  Correspondence  | 

Pattern  Entity  Replacement  Entity 


add 


FIGURE  6.5.  A  simple  transfomiation  rule  with  CompositeActorMatcher  to  remove  hierarchy. 


FIGURE  6.6.  An  example  input  model  for  the  hierarchy-flattening  transformation  in  figure  6.5. 


1.  As  will  be  discussed  below,  flattening  by  transformation  is  a  means  to  syntactically  remove  a  level  of  hierarchy. 
It  does  not  guarantee  the  meaning  of  the  model  (i.e.,  the  correspondence  between  input  sequences  and  output 
sequences)  to  be  preserved  after  transformation. 
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name.  If  the  file  name  of  the  model  in  figure  6.6  is  entered,  the  pattern  matching  algorithm  starts  and 
subgraphs  in  the  model  matched  by  the  pattern  are  looked  for.  In  this  case,  only  one  matched  subgraph 
is  found,  which  consists  of  the  inner  CompositeActor.  1  A  match  viewer  window  opens  and  shows  the 
model,  with  matched  actors  highlighted,  as  in  the  left  part  of  figure  6.7.  In  the  tool  bar  of  this  match 
viewer  window,  there  is  a  EE1  button,  which  the  user  can  click  to  actually  perform  the  transformation 
with  the  highlighted  subgraph.  The  result  is  shown  on  the  right  of  figure  6.7. 

Transformation  of  CompositeActorMatchers  is  specially  implemented  for  manipulating  hierarchy 
in  Ptolemy  models.  To  remove  a  level  of  hierarchy,  as  is  the  case  in  the  previous  example,  a  Compos- 
iteActorMatcher  is  placed  in  the  pattern  to  match  a  CompositeActor  in  the  model,  and  by  not  creating 
a  corresponding  CompositeActorMatcher  in  the  replacement,  the  user  makes  clear  his/her  intent  of 
removing  the  matched  CompositeActor.  The  actors  within  the  CompositeActor,  in  this  case,  the 
AddSubtract  actor,  is  moved  to  the  upper  level,  where  the  CompositeActor  previously  resides.  In  addi¬ 
tions,  the  transformation  mechanism  tries  to  preserve  as  many  connections  between  the  outside  and  the 
inside  of  the  CompositeActor  as  possible.  Here,  the  AddSubtract  actor  is  previously  connected  to  the 
ports  of  the  CompositeActor.  As  the  latter  being  removed,  the  ports  are  removed  as  well.  If  no  extra 
attention  were  taken,  ports  of  the  AddSubtract  actor  would  not  be  connected  in  the  resulting  model.  To 
cope  with  this  without  always  requiring  the  transformation  rule  designer  to  handle  those  connections, 
the  transformation  mechanism  automatically  creates  a  (maybe  implicit)  relation  for  each  port  that  is 
removed  along  with  a  CompositeActor,  and  makes  the  proper  connections  to  that  relation.  Therefore, 
the  actors  moved  to  the  upper  level  are  still  connected.  Note  that  this  does  not  guarantee  the  behavior 
of  the  model  to  be  preserved  after  the  transformation.  This  is  because  transformations  are  purely  syn¬ 
tactic,  whereas  the  behavior  of  the  model  is  dependent  on  the  model(s)  of  computation. 

6.2.3  Constraints 

In  general,  a  pattern  can  have  multiple  matching  subgraphs  in  a  model.  To  restrict  the  matching  so 
that  only  interesting  subgraphs  are  returned,  the  user  may  further  specify  constraints  in  the  “Pattern” 
tab.  This  is  achieved  by  dragging  Constraint  attributes  from  the  library  into  the  canvas,  and  entering  an 
appropriate  expression  as  its  value.  The  expression  must  be  evaluable  at  the  time  of  transformation, 
and  the  result  must  be  boolean.  If  the  expression  cannot  be  evaluated,  either  due  to  unresolved  names 
in  the  expression  or  due  to  malformedness  of  the  expression  itself,  or  if  the  value  that  it  returns  is  not 
boolean,  then  the  constraint  is  simply  considered  false.  No  exception  will  be  visible  to  the  user.  This 
design  is  due  to  the  fact  that  a  constraint  may  or  may  not  be  valid  depending  on  the  input  model  and  the 
matched  subgraph  in  the  model.  If  exceptions  were  always  shown  when  errors  are  found  during  con- 


SDF  Director 


SDF  Director 


FIGURE  6.7.  The  result  of  pattern  matching  (left)  and  transfomiation  (right). 


1.  Even  though  the  model  in  figure  6.6  has  two  CompositeActors,  the  CompositeActorMatcher  in  the  pattern  only 
matches  the  inner  one  because  the  pattern  itself  is  a  CompositeActor,  which  matches  the  top-level  Composite¬ 
Actor  that  is  implicit  in  the  model. 
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straint  evaluation,  then  the  user  had  to  interact  frequently  with  the  transformation  tool.  Moreover,  if  a 
name  cannot  be  resolved  in  a  constraint,  then  it  is  usually  the  case  that  the  matched  subgraph  is  not  the 
one  expected  by  the  transformation  rule  designer. 

In  a  constraint,  the  placeholders  and  the  executable  actors  in  the  pattern  can  be  referred  to  with 
their  names.  For  instance,  the  three  AtomicActorMatchers  in  figure  6. 1  can  be  referred  to  with  “A,” 
“B,”  and  “C.”  The  ports  of  them  can  also  be  referred  to  according  to  a  dot  notation.  For  example,  the 
input  port  of  C  is  written  “C.inpuf  ’  provided  that  the  PortCriterion  corresponding  to  that  port  has  a 
“matcherName”  with  value  “input”  (which  means  the  port  created  for  that  criterion  has  name  “input”). 

In  addition  to  names  that  exist  in  the  pattern,  a  constraint  can  also  refer  to  names  that  are  not  in  the 
pattern  but  in  a  subgraph  that  the  pattern  matches.  For  example,  if  A  in  figure  6.1  matches  a  Const 
actor  in  an  input  model,  then  in  a  constraint,  we  can  specify  expression  “A.value  >  0”  to  test  whether 
the  Const  actor  has  a  “value”  attribute  greater  than  0.  Clearly,  the  name  “value”  can  be  resolved  only 
when  A  matches  an  actor  that  has  an  attribute,  a  port,  or  an  entity  inside  (if  that  actor  is  a  Composi- 
teEntity)  named  “value.”  Furthermore,  if  “value”  is  a  port  or  an  entity,  then  “A.value  >  0”  cannot  be 
evaluated,  so  we  consider  the  constraint  not  being  satisfied. 

A  more  advanced  feature  provided  by  the  constraint  evaluator  allows  the  user  to  invoke  arbitrary 
Java  methods  of  the  Ptolemy  internal  objects,  such  as  actors,  ports  and  attributes.  For  example,  if  A 
matches  a  Const  actor  in  figure  6.1,  constraint  “A.trigger.getWidth()  ==  1”  is  satisfied  only  when  the 
“trigger”  input  port  of  the  Const  actor  has  exactly  one  connection.  Refer  to  Chapter  1  and  Chapter  2  for 
an  in  depth  discussion  on  the  internal  design  of  Ptolemy  objects  and  the  Java  methods  that  they  pro¬ 
vide. 


6.2.4  Transformation  Algorithm 


Figure  6.8  provides  a  sketch  of  the  transformation  algorithm  implement  in  Ptolemy  II.  A  technical 
jargon  red  ex  is  used  here  to  refer  to  a  subgraph  of  the  input  model  that  the  pattern  of  the  transformation 
rule  matches.  Input  to  the  algorithm  is  a  tuple  consisting  of  a  transformation  rule  (as  described  previ¬ 
ously  that  contains  a  pattern,  a  replacement  and  a  correspondence  table)  and  a  source  graph  that  repre¬ 
sents  the  input  model.  Once  a  redex  is  found  that  satisfies  all  the  constraints,  the  transformation  tool 
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FIGURE  6.8.  Transformation  algorithm. 
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invokes  a  callback  function  that  can  be  user-defined  to  decide  whether  the  current  redex  is  desired.  If 
so,  transformation  will  be  applied  to  it  by  first  removing  the  actors  and  relations  that  are  in  the  pattern 
but  are  not  in  the  replacement,  then  adding  the  actors  and  relations  that  are  in  the  replacement  but  are 
not  in  the  pattern,  and  finally  performing  operations  on  the  actors  and  relations  that  are  preserved. 

The  pattern  matching  algorithm  in  the  “Redex  found?”  step  is  an  extension  to  Ullmann’s  back¬ 
tracking  algorithm  for  subgraph  isomoiphism  [148].  This  extension  supports  hierarchical  pattern 
matching,  since  hierarchy  in  the  pattern  can  be  created  with  either  CompositeActor  or  CompositeAc- 
torMatcher.  In  addition,  it  also  supports  an  extensible  set  of  special  attributes  that  the  user  can  specify 
to  control  the  pattern  matching  process.  These  attributes  are  included  in  the  library  on  the  left  of  the 
transformation  rule  editor. 

6.3  Model-Based  Transformation 

Model  transformation  with  a  single  transformation  rule  has  been  discussed  in  the  last  section.  It, 
however,  has  limitations  both  in  performance  and  in  flexibility.  First,  since  pattern  matching  is  essen¬ 
tially  to  solve  a  subgraph  isomoiphism  problem,  its  complexity  is  known  to  be  AP-complete.  There¬ 
fore,  matching  a  model  with  a  large  pattern  (with  100  actors  and  up)  tends  to  be  slow.  No  known 
algorithm  can  significantly  improve  the  performance  of  large  patterns.  Second,  even  though  the  time 
spent  on  matching  a  model  with  a  small  pattern  is  usually  acceptable,  small  patterns  lack  the  necessary 
expressiveness  and  flexibility. 

To  remedy  this  problem,  the  user  is  encouraged  to  write  transformation  rules  with  small  patterns, 
and  to  compose  those  transformation  rules  with  Ptolemy  models.  In  our  implementation,  a  transforma¬ 
tion  rule  specified  in  a  TransformationRule  actor  is  a  model  in  its  own  right,  accepting  inputs  of  model 
tokens  and  sending  outputs  of  new  model  tokens  containing  transformation  results. 

Figure  6.9  shows  a  sample  model  that  controls  two  transformation  rules:  CreateFirst  and  Cre- 
ateOne.  1  At  the  start  of  an  execution,  the  StringConst  actor  is  fired  once  to  produce  a  StringToken  with 
value  “DiningPhilosophers.”  This  token  is  passed  to  the  second  input  port  of  the  ModelGenerator, 
which  generates  an  ActorToken  containing  an  empty  Ptolemy  model  with  name  “DiningPhilosophers.” 
(The  first  input  port  of  the  ModelGenerator,  if  connected,  accepts  StringTokens  containing  the  MoML 


DDF  Director 

#n:  5 


ModelGenerator  CreateFirst 


FIGURE  6.9.  A  model-based  transfomiation  to  generate  a  model  of  5  dining  philosophers. 


1.  This  demo  can  be  accessed  in  ptolemy/actor/gt/demo/DiningPhilosophers  in  the  Ptolemy  tree. 
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descriptions  of  the  models  to  be  generated.)  The  CreateFirst  transformation  rule,  which  the  user  can 
edit  when  looking  inside  of  it  as  in  figure  6.10,  matches  the  empty  model  with  an  empty  pattern.  It  cre¬ 
ates  a  director  and  two  actors  with  connections  between  them  in  the  result  model.  The  Rendezvous 
model  of  computation  is  used  here.  The  CompositeActor  named  “philosopher”  models  a  philosopher 
that  is  ready  to  dine  only  when  he/she  has  a  available  fork  on  each  side.  The  fork  is  modeled  with  a 
ResourcePool  in  the  Rendezvous  model  of  computation  with  one  single  resource  item. 

This  model  with  only  one  philosopher  and  one  fork  is  then  sent  to  the  loop  in  the  downstream.  In 
each  iteration  of  the  loop,  one  more  philosopher  and  one  more  fork  are  added  to  the  model  with  the 
CreateOne  transformation  rule,  shown  in  figure  6.11.  The  loop  executes  n- 1  times  before  the  condition 
specified  in  the  Expression  actor  evaluates  to  true.  At  that  time,  the  model  with  n  philosophers  and  n 
forks  is  sent  to  the  ModelView  actor  to  be  displayed  in  a  new  window.  The  final  output  also  causes  the 
execution  to  terminate. 

Note  that  the  transformation  rule  in  the  CreateOne  actor  is  the  first  one  that  we  discuss  here  with  a 
non-empty  correspondence  table.  The  AtomicActorMatchers  named  “PreviousPhilosopher”  and  “Nex- 
tPool”  correspond  to  the  entities  in  the  replacement  with  the  same  names.  Therefore,  the  internal 
design  of  the  CompositeActor  matched  by  “PreviousPhilosopher”  is  kept  in  the  resulting  model,  as 
well  as  other  ports  of  it  that  are  not  explicitly  mentioned  in  the  AtomicActorMatcher. 

6.4  Implementation 

The  implementation  of  the  model  transformation  mechanism  includes  two  packages.  Package 
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FIGURE  6.10.  The  atomic  transformation  in  the  CreateFirst  actor  in  figure  6.9. 
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FIGURE  6.11.  The  atomic  transformation  in  the  CreateOne  actor  in  figure  6.9. 
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actor.gt  contains  class  definitions  for  the  internal  representation  of  transformation  rules,  as  well  as  the 
transformation  algorithm  based  on  Ullmann’s  backtrack  algorithm  [148].  Within  that  package, 
actor.gt.ingredients. criteria  contains  classes  for  criteria  that  can  be  used  with  AtomicActorMatchers 
and  CompositeActorMatchers  in  the  pattern,  actor.gt.ingredients. operations  contains  classes  for  opera¬ 
tions  for  the  replacement. 

The  user  interface  for  designing  transformation  rules  is  implemented  in  the  vergil.gt  package. 

6.4.1  actor.gt  package 

Figure  6.12  shows  the  relations  between  important  classes  in  the  actor.gt  package.  An  instance  of 


FIGURE  6.12.  Classes  in  the  actor.gt  package. 
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TransformationRule  class  represents  an  atomic  transformation,  which  consists  of  a  pattern  and  a 
replacement  (as  well  as  an  internal  correspondence  table).  Several  attributes  can  be  added  to  the  pat¬ 
tern  and  the  replacement  to  control  pattern  matching  and  the  transformation  process. 

GTIngredient  is  a  superclass  of  Criterion  and  Operation.  Instances  of  those  two  classes  can  be 
added  to  AtomicActorMatchers  and  CompositeActorMatchers,  respectively. 

6.4.2  vergil.gt  package 

Figure  6.13  illustrates  the  classes  in  vergil.gt.  The  key  class  among  those  shown  is  GTFrame, 
which  implements  a  frame  that  employs  different  graph  controllers  to  display  the  TransformationRule 
actor,  as  well  as  other  composite  actors  in  the  transformation  design  and  in  the  view  of  match  result. 

Subclass  TransformationEditor  is  an  editor  for  atomic  transformation  rules.  With  two  different 
graph  controllers,  GTFSMGraphController  and  GTActorGraphController,  the  same  editor  is  used  to 
edit  transformations  for  both  actor  models  and  FSM  (Finite  State  Machine)  models. 

MatchResultViewer  is  another  subclass  of  GTFrame,  which  is  used  to  display  the  result  of  pattern 
matching.  It  highlights  the  matched  entities,  such  as  actors  in  an  actor  model  and  states  in  an  FSM.  The 
highlighting  is  achieved  by  creating  two  controllers  that  subclass  ActorController  and  StateController. 
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Authors:  Christopher  Brooks 

Edward  A.  Lee 

Contributors:  Lukito  Muliadi 
William  Wu 
Jun  Wu 

7.1  Overview 

The  plot  package  provides  classes,  applets,  and  applications  for  two-dimensional  graphical  display 

of  data.  It  is  available  in  a  stand-alone  distribution,  or  as  part  of  the  Ptolemy  II  system. 

There  are  several  ways  to  use  the  classes  in  the  plot  package: 

•  You  can  use  one  of  several  domain-polymorphic  actors  in  a  Ptolemy  II  model  to  plot  data  that  is 
provided  as  an  input  to  the  actor. 

•  You  can  invoke  an  executable,  ptplot,  which  is  a  shell  script,  to  plot  data  in  a  local  file  or  on  the 
network  (via  a  URL). 

•  You  can  invoke  an  executable,  histogram,  which  is  a  shell  script,  to  plot  histograms  of  data  in  a 
local  file  or  on  the  network  (via  a  URL) 

•  You  can  invoke  an  executable,  pxgraph,  which  is  a  shell  script,  to  plot  data  that  is  stored  in  an 
ascii  or  binary  format  compatible  with  the  older  program  pxgraph,  which  is  an  extension  of 
David  Harrison’s  xgraph. 

•  You  can  invoke  a  Java  application,  such  as  PlotMLApplication,  by  using  the  j  ava  program  that  is 
included  in  your  Java  distribution. 

•  You  can  use  an  existing  applet  class,  such  as  PlotMLApplet,  in  an  HTML  file.  The  applet  parame¬ 
ter  dataurl  specifies  the  source  of  plot  data.  You  do  not  even  have  to  have  Ptplot  installed  on 
your  server,  since  you  can  always  reference  the  Berkeley  installation. 

•  You  can  create  new  classes  derived  from  applet,  frame,  or  application  classes  to  customize  your 
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plots.  This  allows  you  to  completely  control  the  placement  of  plots  on  the  screen,  and  to  write  Java 
code  that  defines  the  data  to  be  plotted. 

The  plot  data  can  be  specified  in  any  of  three  data  formats: 

•  PlotML  is  an  XML  extension  for  plot  data.  Its  syntax  is  similar  to  that  of  HTML.  XML  (extensible 
markup  language)  is  an  internet  language  that  is  growing  rapidly  in  popularity. 

•  An  older,  simpler  textual  syntax  for  plot  data  is  also  provided,  although  in  the  long  term,  that  syn¬ 
tax  is  unlikely  to  be  maintained  (it  will  not  necessarily  be  expanded  to  support  new  features).  For 
simple  data  plots,  however,  it  is  adequate.  Using  it  for  applets  has  the  advantage  of  making  it  pos¬ 
sible  to  reference  a  slightly  smaller  jar  file  containing  the  code,  which  makes  for  more  responsive 
applets.  Also,  the  data  files  are  somewhat  smaller. 

•  A  binary  file  format  used  by  pxgraph,  is  supported  by  classes  in  the  compat  package.  Formatting 
information  in  pxgraph  (and  in  the  compat  package)  is  provided  by  command- line  arguments, 
rather  than  being  included  with  the  binary  plot  data,  exactly  as  in  the  older  program.  Applets  spec¬ 
ify  these  command-line  arguments  as  an  applet  parameter  (pxgraphargs). 

7.2  Using  Plots 

If  $PTII  represents  the  home  directory  of  your  Ptplot  installation  (or  your  Ptolemy  II  installation), 
then,  $PTII/bin  is  a  directory  that  contains  a  number  of  executables.  Three  of  these  invoke  plot  applica¬ 
tions,  ptplot,  histogram,  and  pxgraph.  We  recommend  putting  this  directory  into  your  path  so 
that  these  executables  can  be  found  automatically  from  the  command  line.  Invoking  the  command 

ptplot 

with  no  arguments  should  open  a  window  that  looks  like  that  in  figure  7.1.  You  can  also  specify  a  file 
to  plot  as  a  command-line  argument.  To  find  out  about  command- line  options,  type 

ptplot  -help 

The  ptplot  command  is  a  shell  script  that  invokes  the  following  equivalent  command: 

java  -classpath  $PTII  ptolemy . plot . plotml . EditablePlotMLApplication 

Since  it  is  a  shell  script,  it  will  work  on  Unix  machines  and  Windows  machines  that  have  Cygwin1 
installed.  In  the  same  directory  are  three  Windows  versions  that  do  not  require  Cygwin,  ptplot .  bat, 
histogram.bat,  and  pxgraph.bat,  which  you  can  invoke  by  typing  into  the  DOS  command 
prompt,  for  example, 

ptplot . bat 


1.  The  Cygwin  Toolkit  is  a  freely  available  package  available  from 

http://cygwin.com.  A  Ptolemy  II  specific  subset  of  Cygwin  can  be  found  at 
http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/cygwin.htm 
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These  scripts  make  three  assumptions. 

•  First,  j  ava  is  in  your  path.  Type  “  j  ava  -version”  to  verify  that  the  j  ava  program  is  in  your 
path  and  is  working  properly.  Note  that  Ptplot  3.x  and  later  require  Java  1.4  or  later. 

•  Second,  the  environment  variable  PTII  is  set  to  point  to  the  home  directory  of  the  plot  (or  Ptolemy 
II)  installation.  Type  “echo  %PTII%”  in  a  Windows  DOS  shell  and  “echo  $PTll”  in  Unix  or 
Windows  Cygwin  bash  shell  to  check  this. 

•  The  directory  $PTII/bin  is  in  your  path.  Under  Windows  without  Cygwin,  type  “echo  %PATH%”. 
Type  “type  ptplot”  in  Windows  with  Cygwin  and  “which  ptplot”  in  Unix  to  check  this. 

In  Windows,  environment  variables  and  your  path  are  set  in  the  System  control  panel.  You  can  now 
explore  a  number  of  features  of  ptplot. 

7.2.1  Zooming  and  filling 

To  zoom  in,  drag  the  left  mouse  button  down  and  to  the  right  to  draw  a  box  around  an  area  that  you 
want  to  see  in  detail,  as  shown  in  figure  7.2.  To  zoom  out,  drag  the  left  mouse  button  up  and  to  the 
right.  To  just  fill  the  drawing  area  with  the  available  data,  type  Control-F,  or  invoke  the  fill  command 
from  the  Special  menu.  In  applets,  since  there  is  no  menu,  the  fill  command  is  (optionally)  made  avail¬ 
able  as  a  button  at  the  upper  right  of  the  plot. 

7.2.2  Printing  and  exporting 

The  File  menu  includes  a  Print  and  Export  command.  The  Print  command  works  as  you  expect. 
The  export  command  produces  an  encapsulated  PostScript  file  (EPS)  suitable  for  inclusion  in  word 
processors.  The  image  in  figure  7.3  is  such  an  EPS  file  imported  into  FrameMaker. 

At  this  time,  the  EPS  file  does  not  include  preview  data.  This  can  make  it  somewhat  awkward  to 
work  with  in  a  word  processor,  since  it  will  not  be  displayed  by  the  word  processor  while  editing  (it 


FIGURE  7.1.  Result  of  invoking  ptplot  on  the  command  line  with  no  arguments. 
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will,  however,  print  correctly).  It  is  easy  to  add  the  preview  data  using  the  freely  available  program 
Ghostview1.  Just  open  the  file  using  Ghostview  and,  under  the  edit  menu,  select  “Add  EPS  Preview.” 

Export  facilities  are  also  available  from  a  small  set  of  key  bindings,  which  permits  them  to  be 
invoked  from  applets  (which  have  no  menu  bar)  and  from  the  standalone  scripts: 


FIGURE  7.2.  To  zoom  in,  drag  the  left  mouse  button  down  and  to  the  right  to  draw  a  box  around  the  region 
you  wish  to  see  in  more  detail. 


1.  Ghostview  is  available  http://www.cs.wisc.edu/~ghost 
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•  Control-c:  Copy  plot  to  clipboard  (EPS  format),  if  permitted. 

•  D:  Dump  the  plot  to  standard  output  in  PlotML  format. 

•  E:  Export  the  plot  to  standard  output  in  EPS  format. 

•  F:  Fill  the  plot. 

•  H  or  ?:  Display  a  simple  help  message. 

•  Control-d  or  q:  Quit 

The  encapsulated  PostScript  (EPS)  that  is  produced  is  tuned  for  black-and-white  printers.  In  the  future, 
more  formats  may  supported.  Note  that  with  JDK  1.3.0  under  Windows  2000,  Java's  interface  the  clip¬ 
board  may  not  work,  so  Control-C  might  not  accomplish  anything.  Note  further  that  with  applets,  you 
may  find  it  best  to  click  near  the  title  rather  than  clicking  inside  the  graph  itself  and  then  type  the  com¬ 
mand. 

Exporting  to  the  clipboard  and  to  standard  output,  in  theory,  is  allowed  for  applets,  unlike  writing 
to  a  file.  Thus,  these  key  bindings  provide  a  simple  mechanism  to  obtain  a  high-resolution  image  of  the 
plot  from  an  applet,  suitable  for  incorporation  in  a  document.  However,  in  some  browsers,  exporting  to 
standard  out  triggers  a  security  violation.  You  can  use  Sun's  appletviewer  instead. 

7.2.3  Editing  the  data 

You  can  modify  the  data  that  is  plotted  by  first  selecting  a  data  set  to  modify  using  the  Edit  dataset 
command  in  the  Edit  menu,  selecting  a  dataset  and  then  dragging  the  right  mouse  button.  Figure  7.4 
shows  the  result  of  modifying  one  of  the  datasets  (the  one  in  red  on  a  color  display).  The  modification 
is  carried  out  by  freehand  drawing,  although  considerable  precision  is  possible  by  zooming  in.  Use  the 
Save  or  SaveAs  command  in  the  File  menu  to  save  the  modified  plot  (in  PlotML  format). 


FIGURE  7.3.  Encapsulated  postscript  generated  by  the  Export  command  in  the  File  menu  of ptplot  can  be 
imported  into  word  processors.  This  figure  was  imported  into  FrameMaker. 
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7.2.4  Modifying  the  format 

You  can  control  how  data  is  displayed  by  invoking  the  Format  command  in  the  Edit  menu.  This 
brings  up  a  dialog  like  that  at  bottom  in  figure  7.5.  At  the  top  is  the  dialog  and  the  plot  before  changes 
are  made,  and  at  the  bottom  is  after  changes  are  made.  In  particular,  the  grid  has  been  removed,  the 
stems  have  been  removed,  the  lines  connecting  the  data  points  have  been  removed,  the  data  points 
have  been  rendered  with  points,  and  the  color  has  been  removed.  Use  the  Save  or  SaveAs  command  in 
the  File  menu  to  save  the  modified  plot  (in  PlotML  format).  More  sophisticated  control  over  the  plot 
can  be  had  by  editing  the  PlotML  file  (which  is  a  text  file).  The  PlotML  syntax  is  described  below. 

The  entries  in  the  format  dialog  are  all  straightforward  to  use  except  the  “X  Ticks”  and  “Y  Ticks” 
entries.  These  are  used  to  specify  how  the  axes  are  labeled.  The  tick  marks  for  the  axes  are  usually 
computed  automatically  from  the  ranges  of  the  data.  Every  attempt  is  made  to  choose  reasonable  posi¬ 
tions  for  the  tick  marks  regardless  of  the  data  ranges  (powers  of  ten  multiplied  by  1,  2,  or  5  are  used). 
To  change  what  tick  marks  are  included  and  how  they  are  labeled,  enter  into  the  “X  Ticks”  or  “Y 
Ticks”  entry  boxes  a  string  of  the  following  form: 

label  position,  label  position,  ... 

A  label  is  a  string  that  must  be  surrounded  by  quotation  marks  if  it  contains  any  spaces.  A  position  is  a 
number  giving  the  location  of  the  tick  mark  along  the  axis.  For  example,  a  horizontal  axis  for  a  fre¬ 
quency  domain  plot  might  have  tick  marks  as  follows: 


#  Ptolemy  plot 


FIGURE  7.4.  You  can  modify  the  data  being  plotted  by  selecting  a  data  set  and  then  dragging  the  right  mouse 
button.  Use  the  Edit  menu  to  select  a  data  set.  Use  the  Save  command  in  the  File  menu  to  save  the  modified 
plot  (in  PlotML  format). 
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XTicks :  -PI  -3.14159,  -PI/2  -1.570795,  0  0,  PI/2  1.570795,  PI  3.14159 

Tick  marks  could  also  denote  years,  months,  days  of  the  week,  etc. 

7.3  Class  Structure 

The  plot  package  has  two  subpackages,  plotml  and  compat.  The  core  package,  plot,  contains  tool¬ 
kit  classes,  which  are  used  in  Java  programs  as  building  blocks.  The  two  subpackages  contain  classes 
that  are  usable  by  an  end-user  (vs.  a  programmer). 


Set  plot  format 
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FIGURE  7.5.  You  can  control 

how  data  is  displayed  using  the  Format  command  in  the  Edit  menu,  which  brings  up  the  dialog  shown  at  the 
right.  On  the  top  is  before  changes  are  made,  and  on  the  bottom  is  after. 
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7.3.1  Toolkit  classes 

The  class  diagram  for  the  core  of  the  plot  package  is  shown  in  figure  7.6.  These  classes  provide  a 
toolkit  for  constructing  plotting  applications  and  applets.  The  base  class  is  PlotBox,  which  renders  the 
axes  and  the  title.  It  extends  Panel,  a  basic  container  class  in  Java.  Consequently,  plots  can  be  incorpo¬ 
rated  into  virtually  any  Java-based  user  interface. 

The  Plot  class  extends  PlotBox  with  data  sets,  which  are  collections  of  instances  of  PlotPoint.  The 
EditablePlot  class  extends  this  further  by  adding  the  ability  to  modify  data  sets. 

Live  (animated)  data  plots  are  supported  by  the  PlotLive  class.  This  class  is  abstract;  a  derived 
class  must  be  created  to  generate  the  data  to  plot  (or  collect  it  from  some  other  application). 

The  Histogram  class  extends  PlotBox  rather  than  Plot  because  many  of  the  facilities  of  Plot  are 
irrelevant.  This  class  computes  and  displays  a  histogram  from  a  data  file.  The  same  data  file  can  be 
read  by  this  class  and  the  other  plot  classes,  so  you  can  plot  both  the  histogram  and  the  raw  data  that  is 
used  to  generate  it  from  the  same  file. 

7.3.2  Applets  and  applications 

A  number  of  classes  are  provided  to  use  the  plot  toolkit  classes  in  common  ways,  but  you  should 
keep  in  mind  that  these  classes  are  by  no  means  comprehensive.  Many  interesting  uses  of  the  plot 
package  involve  writing  Java  code  to  create  customized  user  interfaces  that  include  one  or  more  plots. 
The  most  commonly  used  built-in  classes  are  those  in  the  plotml  package,  which  can  read  PlotML 
files,  as  well  as  the  older  textual  syntax. 

Ptplot  5.5,  which  shipped  with  Ptolemy  II  5.0  requires  Swing.  The  easiest  way  to  get  Swing  is  to 
install  the  Java  1.4  (or  later)  Plug-in,  which  is  part  of  the  JRE  and  JDK  1.4  installation.  Unfortunately, 
using  the  Java  Plug-in  makes  the  applet  HTML  more  complex.  There  are  two  choices: 

1.  Use  fairly  complex  JavaScript  to  determine  which  browser  is  running  and  then  to  properly  select 
one  of  three  different  ways  to  invoke  the  Java  Plug-in.  This  method  works  on  the  most  different 
types  of  platforms  and  browsers.  The  JavaScript  is  so  complex,  that  rather  than  reproduce  it  here, 
please  see  one  of  the  demonstration  html  files. 

2.  Use  the  much  simpler  <applet>  ...</applet>  tag  to  invoke  the  Java  Plug-in.  This  method  works  on 
many  platforms  and  browsers,  but  requires  a  more  recent  version  of  the  Java  Plug-in,  and  will  not 
work  under  the  very  old  Netscape  Communicator  4.7x. 

Lor  details  about  the  above  two  choices,  see  http://java.sun.com/products/plugin/versions.html. 

We  document  the  much  simpler  <applet>  .  .  .  </applet>  tag  format  below 
The  following  segment  of  HTML  is  an  example: 

<APPLET 

code  =  "ptolemy .plot .plotml . PlotMLApplet" 
codebase  = 

archive  =  "ptolemy/plot/plotmlapplet. jar" 
width  =  "600" 
height  =  "400" 

> 

<PARAM  NAME  =  "background"  VALUE  =  "#faf0e6"  > 

<PARAM  NAME  =  "dataurl"  VALUE  =  "plotmlSample.txt"  > 

No  Java  Plug-in  support  for  applet,  see 

<a  href ="http : //java . sun . com/products/plugin/"><code>http : //java . sun . com/products/plugin/</code></a> 
</APPLET> 

To  use  this  yourself  you  will  probably  need  to  change  the  codebase  and  dataurl  entries.  The  first  points 
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:  various 


:  int) 


+PlotBox() 

+addLegend(dataset :  int,  legend  :  String) 

+addXTick(label :  String,  position  :  double) 

+addYTick(label :  String,  position  :  double) 

+clear(axes :  boolean) 

+clearLegends() 

+deferlfNecessary(action  :  Runnable) 

+export(out :  OutputStream) 

+exportlmage() :  Buffered  I  mage 
+exportlmage(rectangle  :  Rectangle) :  Buffered  I  mage 

+exportlmage(img  :  Bufferedlmage,  r :  Rectangle,  hints  :  RenderingHints,  transp  :  boolean) :  Bufferedlmage] 
+exportlmage(img  :  Bufferedlmage) :  Bufferedlmage 
+fillPlot() 

+getColor() :  boolean 
+getColorByName(name  :  String) :  Color 
+getGrid() :  boolean 
+getLegend(dataset :  int) :  String 
+getMaximumSize() :  Dimension 
+getMinimumSize() :  Dimension 
+getPreferredSize() :  Dimension 
+getTitle() :  String 
+getXLabel() :  String 
+getXLog() :  boolean 
+getXRange() :  doubleQ 
+getXTicks() :  Vector[] 

+getYLabel() :  String 
+getYLog() :  boolean 
+getYRange() :  doublet] 

+getYTicks() :  Vector[] 

+print(g  :  Graphics,  format :  PageFormat,  index 
+read(in  :  InputStream) 

+read(line  :  String) 

+resetAxes() 

+removeLegend(dataset :  int) 

+samplePlot() 

+setBackground(color :  Color) 

+setBounds(x  :  int,  y  :  int,  width  :  int,  height :  int) 

+setButtons(visible :  boolean) 

+setForeground(color :  Color) 

+setGrid(grid  :  boolean) 

+setLabelFont(fontname :  String) 

+setSize(width  :  int,  height :  int) 

+setTitle(title :  String) 

+setTitleFont(fontname  :  String) 

+setWrap(wrap  :  boolean) 

+setXLabel(label :  String) 

+setXLog(log  :  boolean) 

+setXRange(min  :  double,  max  :  double) 

+setYLabel(label :  String) 

+setYLog(log  :  boolean) 

+setYRange(min  :  double,  max  :  double) 

+write(out :  OutputStream) 

+write(out :  OutputStream,  dtd  :  String) 

+write(out :  Writer,  dtd  :  String) 

+writeData(output :  PrintWriter) 

+writeFormat(out :  Writer) 

+zoom(lowx  :  double,  lowy  :  double,  highx  :  double,  highy  :  double) 

#_drawPlot(g  :  Graphics,  clearfirst :  boolean) 

#_drawPoint(g  :  Graphics,  set :  int,  x  :  long,  y  :  long,  clip  :  boolean) 

#_drawPlot(g  :  Graphics,  clear :  boolean,  drawRect :  Rectangle) 

#_help() 

#_parseLine(line  :  String) 

#_setPadding(padding  :  double) 

_zoom(x  :  int,  y  :  int) 

_zoomBox(x  :  int,  y  :  int) 

_zoomStart(x  :  int,  y  :  int) 


+Plot() 

+addPoint(dataset :  int,  x  :  double,  y  :  double,  connected  :  boolean) 

+addPointWithErrorBars(ds  :  int,  x  :  double,  y  :  double,  yLow  :  double,  yHigh  :  double,  cnct :  boolean) 
+clear(dataset :  int) 

+erasePoint(dataset :  int,  index  :  int) 

+getConnected() :  boolean 
+getlmpulses() :  boolean 
+getMarksStyle() :  String 
+getNumDataSets() :  int 
+setBars(on  :  boolean) 

+setBars(width  :  double,  offset :  double) 

+setConnected(on  :  boolean) 

+setConnected(on  :  boolean,  dataset :  int) 

+setlmpulses(on  :  boolean) 

+setlmpulses(on  :  boolean,  dataset :  int) 

+setMarksStyle(style :  String) 

+setMarksStyle(style  :  String,  dataset :  int) 

+setPointsPersistence(numPoints :  int) 

+setReuseDatasets(on  :  boolean) 

+setXPersistence(persistence :  double) 

#_checkDatasetlndex(dataset :  int) 

#_drawBar(g  :  Graphics,  dataset :  int,  x  :  long,  y  :  long,  clip  :  boolean) 

#_drawErrorBar(g  :  Graphics,  dataset :  int,  x  :  long,  ylow  :  long,  yhigh  :  long,  clip  :  boolean) 
#_drawlmpulse(g  :  Graphics,  dataset :  int,  x  :  long,  y  :  long,  clip  :  boolean) 

#_drawLine(g  :  Graphics,  dataset :  int,  startx  :  long,  starty  :  long,  endx  :  long,  endy  :  long,  clip  :  boolean)| 
#_drawPlot(g  :  Graphics,  clearfirst :  boolean) 

#_drawPoint(g  :  Graphics,  dataset :  int,  x  :  long,  y  :  long,  clip  :  boolean) 

#_parseLine(line  :  String) :  boolean 
#_write(output :  PrintWriter) 


~K~ 


EditablePlot 


-_redoStack :  Stack 
-_undoStack :  Stack 
-  editListeners :  Vector 


+EditablePlot() 

+addEditListener(listener :  EditListener) 
+getData(dataset :  int) :  double[|[] 

+redo() 

+removeEditListener(listener :  EditListener)| 
+setEditable(dataset :  int) 

+undo() 


■run() 


PlotPoint 


+x :  double 
+y :  double 
+yLowEB  :  double 
+yHighEB  :  double 
+connected  :  boolean 
+errorBar :  boolean 
+originalX :  double 


Histogram 


+addPoint(dataset :  int,  value  :  double) 

+addPoint(dataset :  int,  x  :  double,  y  :  double,  connected  :  boolean) 
+setBars(width  :  double,  offset :  double) 

+setBinOffset(offset :  double) 

+setBinWidth(width  :  double) 

#_checkDatasetlndex(index :  int) 

#_drawBar(g  :  Graphics,  dataset :  int,  xpos  :  long,  ypos  :  long,  clip  :  boolean)| 


_plotLiveThread  :  Thread 
:  various 


+addPoints() 

+pause() 

+setButtons(visible :  boolean)| 
+start() 

+stop() 


EditListener 


|  +editDataModified(source  :  EditablePlot,  dataset :  int)  \ 


FIGURE  7.6.  The  core  classes  of  the  plot  package. 
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to  the  root  directory  of  the  plot  installation  (usually,  the  value  of  the  PTII  environment  variable).  The 
second  points  to  a  file  containing  data  to  be  plotted,  plus  optional  formatting  information.  The  file  for¬ 
mat  for  the  data  is  described  in  the  next  section.  The  applet  is  created  by  instantiating  the  PlotMLAp- 
plet  class. 

The  archive  entry  contains  the  name  of  the  jar  file  that  contains  all  the  classes  necessary  to  run  a 
PlotML  applet.  The  advantage  of  specifying  a  jar  file  is  that  remote  users  are  likely  to  experience  a 
faster  download  because  all  the  classes  come  over  at  once,  rather  than  the  browser  asking  for  each 
class  from  the  server.  A  downside  of  using  jar  files  in  applets  is  that  if  you  are  modifying  the  source  of 
Ptplot  itself,  then  you  must  also  update  the  jar  file,  or  your  changes  will  not  appear.  A  common 
workaround  is  to  remove  the  archive  entry  during  testing,  or  remove  the  jar  files  themselves. 

You  can  also  easily  create  your  own  applet  classes  that  include  one  or  more  plots.  As  shown  in  fig¬ 
ure  7.6,  the  PlotBox  class  is  derived  from  JPanel,  a  basic  class  Java  Swing.  It  is  easy  to  place  a  panel  in 
an  applet,  positioned  however  you  like,  and  to  combine  multiple  panels  into  an  applet.  PlotApplet  is  a 
simple  class  that  adds  an  instance  of  Plot. 

Creating  an  application  that  includes  one  or  more  plots  is  also  easy.  The  PlotApplication  class, 
shown  in  figure  7.7,  creates  a  single  top-level  window  (a  JFrame),  and  places  within  it  an  instance  of 
Plot.  This  class  is  derived  from  the  PlotFrame  class,  which  provides  a  menu  that  contains  a  set  of  com¬ 
mands,  including  opening  files,  saving  the  plotted  data  to  a  file,  printing,  etc. 

The  difference  between  PlotFrame  and  PlotApplication  is  that  PlotApplication  includes  a  main() 
method,  and  is  designed  to  be  invoked  from  the  command  line.  You  can  invoke  it  using  commands  like 
the  following: 

java  -classpath  $PTII  ptolemy . plot . PlotApplication  args 

However,  the  classes  shown  in  figure  7.7,  which  are  in  the  plot  package,  are  not  usually  the  ones  that 
an  end  user  will  use.  Instead,  use  the  ones  in  figure  7.8.  These  extend  the  base  classes  to  support  the 
PlotML  language,  described  below.  The  only  motivation  for  using  the  base  classes  in  figure  7.7  is  to 
have  a  slightly  smaller  jar  file  to  load  for  applets. 

The  classes  that  end  users  are  likely  to  use,  shown  in  figure  7.8,  include: 

•  PlotMLApplet:  An  applet  that  can  read  PlotML  files  off  the  web  and  render  them. 

•  EditablePlotMLApplet:  A  version  that  allows  editing  of  any  data  set  in  the  plot. 

•  HistogramMLApplet:  A  version  that  uses  the  Histogram  class  to  compute  and  plot  histograms. 

•  PlotMLFrame:  A  top-level  window  containing  a  plot  defined  by  a  PlotML  file. 

•  PlotMLApplication:  An  application  that  can  be  invoked  from  the  command  line  and  reads  PlotML 
files. 

•  EditablePlotMLApplication:  An  extension  that  allows  editing  of  any  data  set  in  the  plot. 

•  HistogramMLApplication:  A  version  that  uses  the  Histogram  class  to  compute  and  plot  histo¬ 
grams. 

EditablePlotMLApplication  is  the  class  invoked  by  the  ptplot  command-line  script.  It  can  open  plot 
files,  edit  them,  print  them,  and  save  them. 
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7.3.3  Writing  applets 

A  plot  can  be  easily  embedded  within  an  applet,  although  there  are  some  subtleties.  The  simplest 
mechanism  looks  like  this: 


public  class  MyApplet  extends  JApplet  { 
public  void  init()  { 
super . init ( ) ; 

Plot  myplot  =  new  Plot(); 
getContentPane ( ) . add (myplot) ; 


FIGURE  7.7.  Core  classes  supporting  applets  and  applications.  Most  of  the  time,  you  will  use  the  classes  in 
the  plotml  package,  which  extend  these  with  the  ability  to  read  PlotML  files. 
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com.microstar.xml  package 


HandlerBase 


+parse(systemld  :  String,  publicld  :  String,  stream  : 
+setHandler(handler :  XmlHandler) 


InputStream,  encoding  :  String)! 


+attribute(name  :  String,  value  :  String,  specified  :  boolean) 
+charData(chars  :  char[],  offset :  int,  length  :  int) 
+endDocument() 

+endElement(elementName  :  String) 

+error(message  :  String,  sysid  :  String,  line  :  int,  column  :  int)] 
+resolveEntity(systemld  :  String,  publicld  :  String) :  Object 
+startDocument() 

+startElement(elementName  :  String) 
+startExternalEntity(systemld  :  String) 


+XmlException(message  :  String,  systemld  :  String,  line  :  int,  column  :  int); 
+getMessage() :  String 
+getSystemld() :  String 
+getLine() :  int 
+getColumn() 


+PlotML_DTD_1  :  String 
#_attributes  :  Hashtable 
#_currentCharData  :  StringBuffer 
#_parser :  XmlParser 
#_plot :  PlotBox 


PlotBoxMLParser() 

PlotBoxMLParser(plot :  PlotBox) 
parse(base  :  URL,  input :  InputStream) 
parse(base  :  URL,  reader :  Reader) 
parse(base  :  URL,  text :  String) 
|#_checkForNull(object :  Object,  message  :  String)] 
#_currentExternalEntity() :  String 


configures 


7T 


#_connected  :  boolean 
#_currentDataset :  int 
#_currentPointCount :  double 
+PlotMLParser() 

PlotMLParser(plot :  Plot) 

|#_addPoint(connected  :  boolean,  elementName  :  String)| 


configures 


plot  package 


PlotApplet 


t-_read(input :  InputStream)! 


+main(args  :  String[j) 
#_about() 

#_read(base  :  URL,  input : 


InputStream)! 


HistgramMLParser 

|+HistogramMLParser(plot : 

Histogram)| 

_ I _ 

PlotMLApplet 

EditablePlotMLApplet 

+PlotMLApplet() 
#_newParser() :  PlotMLParser 

+EditablePlotMLApplet() 

PlotMLApplication 


EditablePlotMLApplication 

|+HistogramMLApplet()| 

+PlotMLApplication() 

+PlotMLApplication(args  :  String!]) 
+PlotMLApplication(plot :  PlotBox,  args  :  String!]) 
#_newParser() :  PlotBoxMLParser 

- 

+EditablePlotMLApplication() 

+EditablePlotMLApplication(args  :  String[j) 
+EditablePlotMLApplication(plot :  EditablePlot,  args  :  String!]) 

HistogramMLApplication 

L 

A 

+HistogramMLApplication() 

+HistogramMLApplication(args  :  String!]) 
+HistogramMLApplication(plot :  Histogram,  args  :  String!]) 

FIGURE  7.8.  UML  static  structure  diagram  for  the  plotml  package,  a  subpackage  of  plot  providing  classes 
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myplot . setTitl e ("Title  of  plot"); 


} 


} 


This  places  the  plot  in  the  center  of  the  applet  space,  stretching  it  to  fill  the  space  available.  To  control 
the  size  independently  of  that  of  the  applet,  for  some  mysterious  reason  that  only  Sun  can  answer,  it  is 
necessary  to  embed  the  plot  in  a  panel,  as  follows: 

public  class  MyApplet  extends  JApplet  { 
public  void  init()  { 
super . init ( ) ; 

Plot  myplot  =  new  Plot(); 

JPanel  panel  =  new  JPanelO; 
getContentPane ( ) .add (panel); 
panel . add (myplot) ; 
myplot. setSize (500,  300); 
myplot . setTitle (" Ti tie  of  plot"); 


} 


The  setSize()  method  specifies  the  width  and  height  in  pixels.  You  will  probably  want  to  control  the 
background  color  and/or  the  border,  using  statements  like: 

myplot . setBackground (background  color) ; 

myplot . setBorder (new  BevelBorder (BevelBorder . RAISED) ) ; 

Alternatively,  you  may  want  to  make  the  plot  transparent,  which  results  in  the  background  showing 
through: 


myplot . setOpaque (false) ; 


7.4  PlotML  File  Format 

Plots  can  be  specified  as  textual  data  in  a  language  called  PlotML,  which  is  an  XML  extension. 
XML,  the  popular  extensible  markup  language ,  provides  a  standard  syntax  and  a  standard  way  of 
defining  the  content  within  that  syntax.  The  syntax  is  a  subset  of  SGML,  and  is  similar  to  HTML.  It  is 
intended  for  use  on  the  internet.  Plot  classes  can  save  data  in  this  format  (in  fact,  the  Save  operation 
always  saves  data  in  this  format),  and  the  classes  in  the  plotml  subpackage,  shown  in  figure  7.8,  can 
read  data  in  this  format.  The  key  classes  supporting  this  syntax  are  PlotBoxMLParser,  which  parses  a 
subset  of  PlotML  supported  by  the  PlotBox  class,  PlotMLParser,  which  parses  the  subset  of  PlotML 
supported  by  the  Plot  class,  and  HistogramMLParser,  which  parses  the  subset  that  supports  histo¬ 
grams. 
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7.4.1  Data  organization 

Plot  data  in  PlotML  has  two  parts,  one  containing  the  plot  data,  including  format  information  (how 
the  plot  looks),  and  the  other  defining  the  PlotML  language.  The  latter  part  is  called  the  document  type 
definition,  or  DTD.  This  dual  specification  of  content  and  structure  is  a  key  XML  innovation. 

Every  PlotML  file  must  either  contain  or  refer  to  a  DTD.  The  simplest  way  to  do  this  is  with  the 
following  file  structure: 

<?xml  version=" 1 . 0 "  standalone="no" ?> 

< ! DOCTYPE  model  PUBLIC  "-//UC  Berkeley//DTD  PlotML  1//EN" 

"http : / /ptolemy . eecs . berkeley . edu/ xml/ dtd/ PlotML_l . dtd"> 

<plot> 

format  commands . . . 
datasets . . . 

</plot> 

Here,  ‘ format  commands”  is  a  set  of  XML  elements  that  specify  what  the  plot  looks  like,  and 
“ datasets ”  is  a  set  of  XML  elements  giving  the  data  to  plot.  The  syntax  for  these  elements  is  described 
below  in  subsequent  sections.  The  first  line  above  is  a  required  part  of  any  XML  file.  It  asserts  the  ver¬ 
sion  of  XML  that  this  file  is  based  on  (1.0)  and  states  that  the  file  includes  external  references  (in  this 
case,  to  the  DTD).  The  second  and  third  lines  declare  the  document  type  (plot)  and  provide  references 
to  the  DTD. 

The  references  to  the  DTD  above  refer  to  a  “public”  DTD.  The  name  of  the  DTD  is 

-//UC  Berkeley/ /DTD  PlotML  1//EN 

which  follows  the  standard  naming  convention  of  public  DTDs.  The  leading  dash  indicates  that 
this  is  not  a  DTD  approved  by  any  standards  body.  The  first  field,  surrounded  by  double  slashes,  in  the 
name  of  the  “owner”  of  the  DTD,  “UC  Berkeley.”  The  next  field  is  the  name  of  the  DTD,  “DTD 
PlotML  1”  where  the  “1”  indicates  version  1  of  the  PlotML  DTD.  The  final  field,  “EN”  indicates  that 
the  language  assumed  by  the  DTD  is  English. 

In  addition  to  the  name  of  the  DTD,  the  DOCTYPE  element  includes  a  URL  pointing  to  a  copy  of 
the  DTD  on  the  web.  If  a  particular  PlotML  tool  does  not  have  access  to  a  local  copy  of  the  DTD,  then 
it  finds  it  at  this  web  site.  PtPlot  recognizes  the  public  DTD,  and  uses  its  own  local  version  of  the  DTD, 
so  it  does  not  need  to  visit  this  website  in  order  to  open  a  PlotML  file. 

An  alternative  way  to  specify  the  DTD  is: 

<?xml  version=" 1 . 0 "  standalone="no" ?> 

<! DOCTYPE  plot  SYSTEM  "DTD  location"> 

<plot> 

format  commands . . . 
datasets . . . 

</plot> 

Here,  the  DTD  location  is  a  relative  or  absolute  URL. 

A  third  alternative  is  to  create  a  standalone  PlotML  file  that  includes  the  DTD.  The  result  is  rather 
verbose,  but  has  the  general  structure  shown  below: 
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<?xml  version="l . 0"  standalone="yes"?> 

< ! DOCTYPE  plot  [ 

DTD  information 

]> 

<plot> 

format  commands 
datasets 
</plot> 

These  latter  two  methods  are  useful  if  you  extend  the  DTD. 

The  DTD  for  PlotML  is  shown  in  figure  7.9.  This  defines  the  PlotML  language.  However,  the 
DTD  is  not  particularly  easy  to  read,  so  we  define  the  language  below  in  a  more  tutorial  fashion. 

7.4.2  Configuring  the  axes 

The  elements  described  in  this  subsection  are  understood  by  the  base  class  PlotBoxMLParser. 

<title> Your  Text  Here</ title> 

The  title  is  bracketed  by  the  start  element  <title>  and  end  element  </title>.  In  XML,  end  ele¬ 
ments  are  always  the  same  as  the  start  element,  except  for  the  slash.  The  DTD  for  this  is  simple: 

<! ELEMENT  title  (#PCDATA)> 

This  declares  that  the  body  consists  of  PCDATA,  parsed  character  data. 

Labels  for  the  X  and  Y  axes  are  similar, 

<xLabel> Your  Text  Here</x Label> 

<yLabel>Your  Text  Here</ yLabel> 

Unlike  HTML,  in  XML,  case  is  important.  So  the  element  is  xLabel  not  XLabel. 

The  ranges  of  the  X  and  Y  axes  can  be  optionally  given  by: 

<xRange  min ="min"  ma x=" max" /> 

<yRange  min ="min"  ma x="max" /> 

The  arguments  min  and  max  are  numbers,  possibly  including  a  sign  and  a  decimal  point.  If  they  are  not 
specified,  then  the  ranges  are  computed  automatically  from  the  data  and  padded  slightly  so  that 
datapoints  are  not  plotted  on  the  axes.  The  DTD  for  these  looks  like: 

<! ELEMENT  xRange  EMPTY> 

< ! ATTLIST  xRange  min  CDATA  # REQUIRED 
max  CDATA  #REQUIRED> 

The  EMPTY  means  that  the  element  does  not  have  a  separate  start  and  end  part,  but  rather  has  a  final 
slash  before  the  closing  character  The  two  ATTLIST  elements  declare  that  min  and  max 
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<! ELEMENT  plot  (barGraph  |  bin  |  dataset  I  default  I  noColor  |  noGrid  I  size  I  title  I  wrap  I  xLabel  I 
xLog  |  xRange  I  xTicks  I  yLabel  I  yLog  I  yRange  I  yTicks)*> 

<! ELEMENT  barGraph  EMPTY> 

< ! ATTLIST  barGraph  width  CDATA  #IMPLIED 

offset  CDATA  #IMPLIED> 

<! ELEMENT  bin  EMPTY> 

<! ATTLIST  bin  width  CDATA  # IMPLIED 

offset  CDATA  #IMPLIED> 

<! ELEMENT  dataset  (m  |  move  I  p  I  point) *> 

<! ATTLIST  dataset  connected  (yes  I  no)  # IMPLIED 

marks  (none  I  dots  I  points  I  various  I  pixels)  #IMPLIED 

name  CDATA  # IMPLIED 

stems  (yes  I  no)  #IMPLIED> 

<! ELEMENT  default  EMPTY> 

< (ATTLIST  default  connected  (yes  I  no)  "yes" 

marks  (none  I  dots  I  points  I  various  I  pixels)  "none" 
stems  (yes  I  no)  "no"> 

<! ELEMENT  noColor  EMPTY> 

<! ELEMENT  noGrid  EMPTY> 

<! ELEMENT  reuseDatasets  EMPTY> 

<! ELEMENT  size  EMPTY> 

< (ATTLIST  size  height  CDATA  # REQUIRED 
width  CDATA  #REQUIRED> 

<! ELEMENT  title  (#PCDATA)> 

<! ELEMENT  wrap  EMPTY> 

<! ELEMENT  xLabel  (#PCDATA)> 

<! ELEMENT  xLog  EMPTY> 

<! ELEMENT  xRange  EMPTY> 

< (ATTLIST  xRange  min  CDATA  # REQUIRED 
max  CDATA  #REQUIRED> 

<! ELEMENT  xTicks  (tick)+> 

<! ELEMENT  yLabel  (#PCDATA)> 

<! ELEMENT  yLog  EMPTY> 

<! ELEMENT  yRange  EMPTY> 

< (ATTLIST  yRange  min  CDATA  # REQUIRED 
max  CDATA  #REQUIRED> 

<! ELEMENT  yTicks  (tick)+> 

<! ELEMENT  tick  EMPTY> 

< (ATTLIST  tick  label  CDATA  # REQUIRED 

position  CDATA  #REQUIRED> 

<! ELEMENT  m  EMPTY> 

< (ATTLIST  m  x  CDATA  #IMPLIED 
y  CDATA  # REQUIRED 
lowErrorBar  CDATA  #IMPLIED 
highErrorBar  CDATA  #IMPLIED> 

<! ELEMENT  move  EMPTY> 

< (ATTLIST  move  x  CDATA  #IMPLIED 
y  CDATA  # REQUIRED 
lowErrorBar  CDATA  #IMPLIED 
highErrorBar  CDATA  #IMPLIED> 

<! ELEMENT  p  EMPTY> 

< (ATTLIST  p  x  CDATA  #IMPLIED 
y  CDATA  # REQUIRED 
lowErrorBar  CDATA  #IMPLIED 
highErrorBar  CDATA  #IMPLIED> 

<! ELEMENT  point  EMPTY> 

< (ATTLIST  point  x  CDATA  #IMPLIED 
y  CDATA  # REQUIRED 
lowErrorBar  CDATA  #IMPLIED 
highErrorBar  CDATA  #IMPLIED> 

FIGURE  7.9.  The  document  type  definition  (DTD)  for  the  PlotML  language. 
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attributes  are  required,  and  that  they  consist  of  character  data. 

The  tick  marks  for  the  axes  are  usually  computed  automatically  from  the  ranges.  Every  attempt  is 
made  to  choose  reasonable  positions  for  the  tick  marks  regardless  of  the  data  ranges  (powers  of  ten 
multiplied  by  1,  2,  or  5  are  used).  However,  they  can  also  be  specified  explicitly  using  elements  like: 

<xTicks> 

<tick  label=" label"  position =" position" /> 

<tick  label =" label"  position =” position" /> 

</ xTicks> 

A  label  is  a  string  that  replaces  the  number  labels  on  the  axes.  A  position  is  a  number  giving  the  loca¬ 
tion  of  the  tick  mark  along  the  axis.  For  example,  a  horizontal  axis  for  a  frequency  domain  plot  might 
have  tick  marks  as  follows: 

<xTicks> 

<tick  label="-PI"  position="-3 . 14159"/> 

<tick  label="-PI/2"  position="-l . 570795"/> 

<tick  label="0"  position=" 0 " /> 

<tick  label="PI/2"  position="l . 570795"/> 

<tick  label="PI"  position="3 . 14159"/> 

</ xTicks> 

Tick  marks  could  also  denote  years,  months,  days  of  the  week,  etc.  The  relevant  DTD  information  is: 

<! ELEMENT  xTicks  (tick)+> 

<! ELEMENT  tick  EMPTY> 

< ! ATTLIST  tick  label  CDATA  # REQUIRED 

position  CDATA  #REQUIRED> 

The  notation  (tick)  +  indicates  that  the  xTicks  element  contains  one  or  more  tick  elements. 

If  ticks  are  not  specified,  then  the  X  and  Y  axes  can  use  a  logarithmic  scale  with  the  following  ele¬ 
ments: 


<xLog/> 

<yLog/> 

The  tick  labels,  which  are  computed  automatically,  represent  powers  of  10.  The  log  axis  facility  has  a 
number  of  limitations,  which  are  documented  in  “Limitations”  on  page  7-170. 

By  default,  tick  marks  are  connected  by  a  light  grey  background  grid.  This  grid  can  be  turned  off 
with  the  following  element: 

<noGrid/ > 

Also,  by  default,  the  first  ten  data  sets  are  shown  each  in  a  unique  color.  The  use  of  color  can  be  turned 
off  with  the  element: 
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<noColor/> 

Finally,  the  rather  specialized  element 

<wrap/> 

enables  wrapping  of  the  X  (horizontal)  axis,  which  means  that  if  a  point  is  added  with  X  out  of  range, 
its  X  value  will  be  modified  modulo  the  range  so  that  it  lies  in  range.  This  command  only  has  an  effect 
if  the  X  range  has  been  set  explicitly.  It  is  designed  specifically  to  support  oscilloscope-like  behavior, 
where  the  X  value  of  points  is  increasing,  but  the  display  wraps  it  around  to  left.  A  point  that  lands  on 
the  right  edge  of  the  X  range  is  repeated  on  the  left  edge  to  give  a  better  sense  of  continuity.  The  fea¬ 
ture  works  best  when  points  do  land  precisely  on  the  edge,  and  are  plotted  from  left  to  right,  increasing 
in  X. 

You  can  also  specify  the  size  of  the  plot,  in  pixels,  as  in  the  following  example: 

<size  width="400"  height="300"> 

All  of  the  above  commands  can  also  be  invoked  directly  by  calling  the  corresponding  public  meth¬ 
ods  from  Java  code. 

7.4.3  Configuring  data 

Each  data  set  has  the  form  of  the  following  example 

<dataset  name="grades"  marks="dots"  connected="no"  stems="no"> 
data 

</dataset> 

All  of  the  arguments  to  the  dataset  element  are  optional.  The  name,  if  given,  will  appear  in  a  legend 
at  the  upper  right  of  the  plot.  The  marks  option  can  take  one  of  the  following  values: 

•  none:  (the  default)  No  mark  is  drawn  for  each  data  point. 

•  points:  A  small  point  identifies  each  data  point. 

•  dots:  A  larger  circle  identifies  each  data  point. 

•  various:  Each  dataset  is  drawn  with  a  unique  identifying  mark.  There  are  10  such  marks,  so  they 
will  be  recycled  after  the  first  10  data  sets. 

•  pixels:  A  single  pixel  identified  each  data  point. 

The  connected  argument  can  take  on  the  values  “yes”  and  “no.”  It  determines  whether  successive 
datapoints  are  connected  by  a  line.  The  default  is  that  they  are.  Finally,  the  stems  argument,  which  can 
also  take  on  the  values  “yes”  and  “no,”  specifies  whether  stems  should  be  drawn.  Stems  are  lines 
drawn  from  a  plotted  point  down  to  the  x  axis.  Plots  with  stems  are  often  called  “stem  plots.” 

The  DTD  is: 

<! ELEMENT  dataset  (m  |  move  |  p  |  point) *> 

<!ATTLIST  dataset  connected  (yes  |  no)  #IMPLIED 

marks  (none  |  dots  |  points  |  various  |  pixels)  #IMPLIED 
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name  CDATA  #IMPLIED 
stems  (yes  |  no)  #IMPLIED> 

The  default  values  of  these  arguments  can  be  changed  by  preceding  the  dataset  elements  with  a 
default  element,  as  in  the  following  example: 

<default  connected="no"  marks="dots"  stems="yes"/> 

The  DTD  for  this  element  is: 

<! ELEMENT  default  EMPTY> 

<!ATTLIST  default  connected  (yes  |  no)  "yes" 

marks  (none  |  dots  |  points  |  various  |  pixels)  "none" 
stems  (yes  |  no)  "no"> 

If  the  following  element  occurs: 

<reuseDatasets/> 

then  datasets  with  the  same  name  will  be  merged.  This  makes  it  easier  to  combine  multiple  data  files 
that  contain  the  same  datasets  into  one  file.  By  default,  this  capability  is  turned  off,  so  datasets  with  the 
same  name  are  not  merged. 

7.4.4  Specifying  data 

A  dataset  has  the  form 

<dataset  options> 
data 

</dataset> 

The  data  itself  are  given  by  a  sequence  of  elements  with  one  of  the  following  forms: 

<point  y =" yValue"> 

<point  x=" xValue"  y =" yValue"> 

<point  y  =" yValue"  lowErrorBar=" low"  highErrorBar="higii"> 

<point  x=" xValue"  y  =" yValue"  lowErrorBar=" low"  highErrorBar="iiigii"> 

To  reduce  file  size  somewhat,  they  can  also  be  given  as 

<p  y=" yValue"> 

<p  x=" xValue"  y  ='' yValue"> 

<p  y=" yValue"  lowErrorBar=" low"  highErrorBar="iiigh"> 

<p  x=" xValue"  y  =" yValue"  lowErrorBar=" low"  highErrorBar="iiigii"> 

The  first  form  specifies  only  a  Y  value.  The  X  value  is  implied  (  it  is  the  count  of  points  seen  before  in 
this  data  set).  The  second  form  gives  both  the  X  and  Y  values.  The  third  and  fourth  forms  give  low  and 
high  error  bar  positions  (error  bars  are  use  to  indicate  a  range  of  values  with  one  data  point).  Points 
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given  using  the  syntax  above  will  be  connected  by  lines  if  the  connected  option  has  been  given  value 
“yes”  (or  if  nothing  has  been  said  about  it). 

Data  points  may  also  be  specified  using  one  of  the  following  forms: 

<move  y=" yValue"> 

<move  x=" xValue"  y =" yValue”> 

<move  y=" yValue"  lowErrorBar=" low"  highErrorBar =" high"> 

<move  x=" xValue"  y  =" yValue”  lowErrorBar=" low"  highErrorBar="higii"> 

<m  y  =" yValue"> 

<m  x=" xValue”  y=" yValue"> 

<m  y =” yValue"  lowErrorBar=" low"  highErrorBar ="high"> 

<m  x=" xValue"  y  =" yValue"  lowErrorBar="ioiv"  highErrorBar  =" high"> 

This  causes  a  break  in  connected  points,  if  lines  are  being  drawn  between  points.  I.e.,  it  overrides  the 
connected  option  for  the  particular  data  point  being  specified,  and  prevents  that  point  from  being 
connected  to  the  previous  point. 

7.4.5  Bar  graphs 

To  create  a  bar  graph,  use: 

<barGraph  width=" barWidth"  offset =" barOffset" /> 

You  will  also  probably  want  the  connected  option  to  have  value  “no.”  The  barWidth  is  a  real  num¬ 
ber  specifying  the  width  of  the  bars  in  the  units  of  the  X  axis.  The  barOffset  is  a  real  number  speci¬ 
fying  how  much  the  bar  of  the  z-th  data  set  is  offset  from  the  previous  one.  This  allows  bars  to  “peek 
out”  from  behind  the  ones  in  front.  Note  that  the  front-most  data  set  will  be  the  first  one. 

7.4.6  Histograms 

To  configure  a  histogram  on  a  set  of  data,  use 

<bin  width=" binWidth"  offset =”binOffset”/> 

The  binWidth  option  gives  the  width  of  a  histogram  bin.  I.e.,  all  data  values  within  one  binWidth 
are  counted  together.  The  binOffset  value  is  exactly  like  the  barOffset  option  in  bar  graphs.  It 
specifies  by  how  much  successive  histograms  “peek  out.” 

Histograms  work  only  on  Y  data;  X  data  is  ignored. 

7.5  Old  Textual  File  Format 

Instances  of  the  PlotBox  and  Plot  classes  can  read  a  simple  file  format  that  specifies  the  data  to  be 
plotted.  This  file  format  predates  the  PlotML  format,  and  is  preserved  primarily  for  backward  compat¬ 
ibility.  In  addition,  it  is  significantly  more  concise  than  the  PlotML  syntax,  which  can  be  advanta¬ 
geous,  particularly  in  networked  applications. 

In  this  older  syntax,  each  file  contains  a  set  of  commands,  one  per  line,  that  essentially  duplicate 
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the  methods  of  these  classes.  There  are  two  sets  of  commands  currently,  those  understood  by  the  base 
class  PlotBox,  and  those  understood  by  the  derived  class  Plot.  Both  classes  ignore  commands  that  they 
do  not  understand.  In  addition,  both  classes  ignore  lines  that  begin  with  “#”,  the  comment  character. 
The  commands  are  not  case  sensitive. 

7.5.1  Commands  Configuring  the  Axes 

The  following  commands  are  understood  by  the  base  class  PlotBox.  These  commands  can  be 
placed  in  a  file  and  then  read  via  the  read()  method  of  PlotBox,  or  via  a  URL  using  the  PlotApplet 
class.  The  recognized  commands  include: 

•  TitleText :  string 

•  XLabel:  string 

•  YLabel:  string 

These  commands  provide  a  title  and  labels  for  the  X  (horizontal)  and  Y  (vertical)  axes.  A  string  is 
simply  a  sequence  of  characters,  possibly  including  spaces.  There  is  no  need  here  to  surround  them 
with  quotation  marks,  and  in  fact,  if  you  do,  the  quotation  marks  will  be  included  in  the  labels. 

The  ranges  of  the  X  and  Y  axes  can  be  optionally  given  by  commands  like: 

•  XRange :  min,  max 

•  YRange :  min,  max 

The  arguments  min  and  max  are  numbers,  possibly  including  a  sign  and  a  decimal  point.  If  they  are  not 
specified,  then  the  ranges  are  computed  automatically  from  the  data  and  padded  slightly  so  that 
datapoints  are  not  plotted  on  the  axes. 

The  tick  marks  for  the  axes  are  usually  computed  automatically  from  the  ranges.  Every  attempt  is 
made  to  choose  reasonable  positions  for  the  tick  marks  regardless  of  the  data  ranges  (powers  of  ten 
multiplied  by  1,  2,  or  5  are  used).  However,  they  can  also  be  specified  explicitly  using  commands  like: 

•  XTicks:  label  position,  label  position,  ... 

•  YTicks:  label  position,  label  position,  ... 

A  label  is  a  string  that  must  be  surrounded  by  quotation  marks  if  it  contains  any  spaces.  A  position  is 
a  number  giving  the  location  of  the  tick  mark  along  the  axis.  For  example,  a  horizontal  axis  for  a  fre¬ 
quency  domain  plot  might  have  tick  marks  as  follows: 

XTicks:  -PI  -3.14159,  -PI/2  -1.570795,  0  0,  PI/2  1.570795,  PI  3.14159 

Tick  marks  could  also  denote  years,  months,  days  of  the  week,  etc. 

The  X  and  Y  axes  can  use  a  logarithmic  scale  with  the  following  commands: 

•  XLog:  on 

•  YLog:  on 

The  tick  labels,  if  computed  automatically,  represent  powers  of  1 0.  The  log  axis  facility  has  a  number 
of  limitations,  which  are  documented  in  “Limitations”  on  page  7-170. 

By  default,  tick  marks  are  connected  by  a  light  grey  background  grid.  This  grid  can  be  turned  off 
with  the  following  command: 

•  Grid:  off 

It  can  be  turned  back  on  with 

•  Grid:  on 
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Also,  by  default,  the  first  ten  data  sets  are  shown  each  in  a  unique  color.  The  use  of  color  can  be 
turned  off  with  the  command: 

•  Color:  off 

It  can  be  turned  back  on  with 

•  Color:  on 

Finally,  the  rather  specialized  command 

•  Wrap:  on 

enables  wrapping  of  the  X  (horizontal)  axis,  which  means  that  if  a  point  is  added  with  X  out  of  range, 
its  X  value  will  be  modified  modulo  the  range  so  that  it  lies  in  range.  This  command  only  has  an  effect 
if  the  X  range  has  been  set  explicitly.  It  is  designed  specifically  to  support  oscilloscope-like  behavior, 
where  the  X  value  of  points  is  increasing,  but  the  display  wraps  it  around  to  left.  A  point  that  lands  on 
the  right  edge  of  the  X  range  is  repeated  on  the  left  edge  to  give  a  better  sense  of  continuity.  The  fea¬ 
ture  works  best  when  points  do  land  precisely  on  the  edge,  and  are  plotted  from  left  to  right,  increasing 
in  X. 

All  of  the  above  commands  can  also  be  invoked  directly  by  calling  the  corresponding  public  meth¬ 
ods  from  some  Java  code. 


7.5.2  Commands  for  Plotting  Data 


The  set  of  commands  understood  by  the  Plot  class  support  specification  of  data  to  be  plotted  and 
control  over  how  the  data  is  shown. 

The  style  of  marks  used  to  denote  a  data  point  is  defined  by  one  of  the  following  commands: 


•  Marks: 

•  Marks: 

•  Marks: 

•  Marks: 

•  Marks: 


none 

points 

dots 

various 

pixels 


Here,  points  are  small  dots,  while  dots  are  larger.  If  various  is  specified,  then  unique  marks  are 
used  for  the  first  ten  data  sets,  and  then  recycled.  If  pixels  is  specified,  then  a  single  pixel  is  drawn. 
Using  no  marks  is  useful  when  lines  connect  the  points  in  a  plot,  which  is  done  by  default.  If  the  above 
directive  appears  before  any  DataSet  directive,  then  it  specifies  the  default  for  all  data  sets.  If  it 
appears  after  a  DataSet  directive,  then  it  applies  only  to  that  data  set. 

To  disable  connecting  lines,  use: 


•  Lines:  off 


To  re-enable  them,  use 

•  Lines:  on 


You  can  also  specify  “impulses”,  which  are  lines  drawn  from  a  plotted  point  down  to  the  x  axis. 
Plots  with  impulses  are  often  called  “stem  plots.”  These  are  off  by  default,  but  can  be  turned  on  with 
the  command: 

•  Impulses:  on 

or  back  off  with  the  command 

•  Impulses:  off 

If  that  command  appears  before  any  DataSet  directive,  then  the  command  applies  to  all  data  sets.  Oth¬ 
erwise,  it  applies  only  to  the  current  data  set. 
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To  create  a  bar  graph,  turn  offlines  and  use  any  of  the  following  commands: 

•  Bars :  on 

•  Bars:  width 

•  Bars:  width,  offset 

The  width  is  a  real  number  specifying  the  width  of  the  bars  in  the  units  of  the  x  axis.  The  offset  is  a 
real  number  specifying  how  much  the  bar  of  the  i-th  data  set  is  offset  from  the  previous  one.  This 
allows  bars  to  “peek  out”  from  behind  the  ones  in  front.  Note  that  the  front-most  data  set  will  be  the 
first  one.  To  turn  off  bars,  use 

•  Bars:  off 

To  specify  data  to  be  plotted,  start  a  data  set  with  the  following  command: 

•  DataSet:  string 

Here,  string  is  a  label  that  will  appear  in  the  legend.  It  is  not  necessary  to  enclose  the  string  in  quota¬ 
tion  marks. 

To  start  a  new  dataset  without  giving  it  a  name,  use: 

•  DataSet: 

In  this  case,  no  item  will  appear  in  the  legend. 

If  the  following  directive  occurs: 

•  ReuseDataSets :  on 

then  datasets  with  the  same  name  will  be  merged.  This  makes  it  easier  to  combine  multiple  data  files 
that  contain  the  same  datasets  into  one  file.  By  default,  this  capability  is  turned  off,  so  datasets  with  the 
same  name  are  not  merged. 

The  data  itself  is  given  by  a  sequence  of  commands  with  one  of  the  following  forms: 

•  x,  y 

•  draw:  x,  y 

•  move :  x,  y 

•  x,  y,  yLowErrorBar ,  yHighErrorBar 

•  draw:  x,  y,  yLowErrorBar,  yHighErrorBar 

•  move:  x,  y,  yLowErrorBar,  yHighErrorBar 

The  draw  command  is  optional,  so  the  first  two  forms  are  equivalent.  The  move  command  causes  a 
break  in  connected  points,  if  lines  are  being  drawn  between  points.  The  numbers  x  and  y  are  arbitrary 
numbers  as  supported  by  the  Double  parser  in  Java  (e.g.  “1.2”,  “6.39e-15”,  etc.).  If  there  are  four  num¬ 
bers,  then  the  last  two  numbers  are  assumed  to  be  the  lower  and  upper  values  for  error  bars.  The  num¬ 
bers  can  be  separated  by  commas,  spaces  or  tabs. 

7.6  Compatibility 

Figure  7.10  shows  a  small  set  of  classes  in  the  compat  package  that  support  an  older  ascii  and 
binary  file  formats  used  by  the  popular  pxgraph  program  (an  extension  of  xgraph  to  support  binary 
formats).  The  PxgraphApplication  class  can  be  invoked  by  the  pxgraph  executable  in  $PTII/bin.  See 
the  PxgraphParser  class  documentation  for  information  about  the  file  format. 
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7.7  Limitations 

The  plot  package  is  a  starting  point,  with  a  number  of  significant  limitations. 

•  A  binary  file  format  that  includes  plot  format  information  is  needed.  This  should  be  an  extension 
of  PlotML,  where  an  external  entity  is  referenced. 

•  If  you  zoom  in  far  enough,  the  plot  becomes  unreliable.  In  particular,  if  the  total  extent  of  the  plot 
is  more  than  232  times  extent  of  the  visible  area,  quantization  errors  can  result  in  displaying  points 
or  lines.  Note  that  2  is  over  4  billion. 

•  The  log  axis  facility  has  a  number  of  limitations.  Note  that  if  a  logarithmic  scale  is  used,  then  the 
values  must  be  positive.  Non-positive  values  will  be  silently  dropped.  Further  log  axis  limita¬ 
tions  are  listed  in  the  documentation  of  the  _gridlnit()  method  in  the  PlotBox  class. 

•  Graphs  cannot  be  currently  copied  via  the  clipboard. 


FIGURE  7.10.  The  compat  package  provides  compatibility  with  the  older  pxgraph  program. 
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8.1  Motivation 

Ptolemy  II  is  a  software  lab  for  experimenting  with  multiple  concurrency  formalisms  for  embed¬ 
ded  system  design.  Many  features  in  Ptolemy  II  contribute  to  the  ease  of  its  use  as  a  rapid  prototyping 
environment.  In  particular,  modular  components  make  systems  more  flexible  and  extensible.  Different 
compositions  of  the  same  components  can  implement  different  functionality.  However,  component 
designs  are  often  slower  than  custom-built  code.  The  cost  of  inter-component  communication  through 
the  component  interface  introduces  overhead,  and  generic  components  are  highly  parameterized  for 
the  reusability  and  thus  less  efficient. 

To  regain  the  efficiency  for  the  implementation,  the  users  could  write  big  monolithic  components 
to  reduce  inter-component  communication,  and  write  highly  specialized  components  rather  than  gen¬ 
eral  ones.  However,  manually  implementing  these  solutions  is  not  an  option.  Partial  evaluation  [66] 
provides  a  mechanism  to  automate  the  whole  process.  In  the  past,  partial  evaluation  has  been  mostly 
used  for  general  purpose  software.  Recently,  partial  evaluation  has  begun  to  see  its  use  in  the  embed¬ 
ded  world,  e.g.,  see  [72],  In  our  research  partial  evaluation  is  used  as  a  code  generation  technique, 
which  is  really  a  compilation  technique  for  transforming  an  actor-oriented  model  into  the  target  code 
while  preserving  the  model’s  semantics.  However,  compared  with  traditional  compiler  optimization, 
partial  evaluation  for  embedded  software  works  at  the  component  level  and  heavily  leverages  the 
domain-specific  knowledge.  Through  model  analysis,  the  tool  can  discover  data  type,  buffer  size, 
parameter  value,  model  structure  and  model  execution  schedule,  and  then  partially  evaluate  all  the 
known  information  to  reach  a  very  efficient  implementation.  The  end  result  is  that  the  benefit  offered 
by  the  high  level  abstraction  comes  with  (almost)  no  performance  penalty. 
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FIGURE  8.1.  The  C/C++  Development  Toolkit  (CDT)  in  the  Eclipse  Integrated  Development  Environment. 


8.2  A  Helper-based  Mechanism 

Our  code  generation  framework  uses  a  helper-based  mechanism.  A  codegen  helper  is  essentially  a 
component  that  generates  code  for  a  Ptolemy  II  actor.  Each  Ptolemy  II  actor  for  which  code  will  be 
generated  in  a  specific  language  has  one  associated  helper.  An  actor  may  have  multiple  helpers  to  sup¬ 
port  multiple  target  languages  (C,  VHDL,  etc.). 

To  achieve  readability  and  maintainability  in  the  implementation  of  helper  classes,  the  target  code 
blocks  (for  example,  the  initialize  block,  fire  block,  and  wrapup  block)  of  each  helper  are  placed  in  a 
separate  file  under  the  same  directory.  So  a  helper  essentially  consists  of  two  files:  a  java  class  file  and 
a  code  template  file.  This  not  only  decouples  the  writing  of  Java  code  and  target  code  (otherwise  the 
target  code  would  be  wrapped  in  strings  and  interspersed  with  java  code),  but  also  allows  using  a  target 
language  specific  editor  while  working  on  the  target  language  code  blocks.  For  example,  in  the  Eclipse 
Integrated  Development  Environment,  the  C/C++  Development  Toolkit  (CDT)  provides  C  and  C++ 
extensions  to  the  Eclipse  workbench  as  a  set  of  Eclipse  plug-ins,  see  figure  8.1.  The  convenient  fea¬ 
tures  such  as  keyword  highlights  in  the  C/C++  specific  editor  could  help  the  writing  of  C  code,  result¬ 
ing  in  improved  productivity. 

So  the  code  template  file  contains  code  blocks  written  in  the  target  language.  The  target  code 
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//  CountTrues.c 

/***  preinitBlock  ***/ 
int  $actorSymbol (trueCount) ; 
int  $actorSymbol (i) ; 

/**/ 

/***  fireBlock  ***/ 

$actorSymbol (trueCount)  =  0; 

for  ($actorSymbol (i)  =  0;  $actorSymbol (i)  <  $val (blockSize) ;  $actorSymbol (i) ++)  { 
if  ($ref (input,  $actorSymbol (i) ) )  { 

$actorSymbol (trueCount) ++; 

} 

} 

$ref  (output)  =  $actorSymbol (trueCount)  ; 

/**/ 


FIGURE  8.2.  The  C  code  template  file  for  the  CountTrues  helper. 

blocks  are  hand-coded  so  users  have  flexibility  in  choosing  their  design  styles  and  algorithms.  Hand- 
coded  templates  also  retain  readability  in  the  generated  code.  The  codegen  kernel  uses  the  java  class  of 
the  helper  to  harvest  code  blocks  from  the  code  template  file.  The  java  class  of  the  helper  determines 
which  code  blocks  to  harvest  based  on  the  actor  instance-specific  information  (e.g.,  port  type,  port 
width,  and  parameter  values).  The  code  template  file  contains  codegen  macros  that  are  processed  by 
the  codegen  kernel.  These  macros  allow  the  kernel  to  generate  customized  code  based  on  the  actor 
instance-specific  information. 

8.2.1  What  is  in  a  C  Code  Template  File? 

A  C  code  template  file  has  a  .c  file  extension  but  it  is  not  C-compilable  due  to  its  unique  structure. 
Only  the  CodeStream  object  understands  how  to  parse  and  use  these  files.  Figure  8.2  shows  the  C  code 
template  file  for  the  CountTrues  helper,  located  in  $PTII/ptolemy/codegen/c/domains/sdf/lib. 

A  C  code  template  file  consists  of  one  or  more  C  code  blocks.  Each  code  block  has  a  header  and  a 
footer.  The  helper  uses  a  CodeStream  object  to  parse  the  code  blocks.  Please  refer  to  Appendix  C  for  a 
detailed  documentation  of  the  CodeStream  object.  The  header  and  footer  tags  are  code  block  separa¬ 
tors  that  help  the  CodeStream  in  parsing.  The  footer  is  simply  the  tag  “/**/”.  The  header  starts  with  the 
begin  tag  “/***”  and  ends  with  the  end  tag  “***/”.  The  header  also  contains  a  code  block  name  and 
optionally  a  parameter  list.  The  parameter  list  is  enclosed  by  a  pair  of  parentheses  “()”  and  multiple 
parameters  in  the  list  are  separated  by  commas  A  code  block  may  have  arbitrary  number  of  param¬ 
eters.  Each  parameter  is  prefixed  by  the  dollar  sign  “$”  symbol  (i.e.  $value,  Swidth,  etc.),  which  allows 
the  CodeStream  object  to  do  a  straight  text  substitution  with  the  string  value  of  the  parameter.  For¬ 
mally,  the  signature  of  a  code  block  is  defined  as  the  pair  (N,  p)  where  N  is  the  code  block  name  and  p 
is  the  number  of  parameters.  A  code  block  (N,  p)  may  be  overloaded  by  another  code  block  (N,  p’)1. 
Furthermore,  different  helpers  in  a  class  hierarchy  may  contain  code  blocks  with  the  same  (N,  p).  So  a 
unique  reference  to  a  code  block  signature  is  the  tuple  (H,  N,  p)  where  H  is  the  corresponding  helper. 
Defining  the  uniqueness  of  a  code  block  prevents  unambiguity  in  referencing  a  code  block. 


1.  All  parameters  in  a  code  block  are  implicitly  strings.  So  unlike  the  usual  overloaded  functions  with  the  same 
name  but  different  types  of  parameters,  we  need  different  number  of  parameters  to  have  an  overload  relationship 
for  code  blocks. 
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public  String  generateFireCode ( )  throws  IllegalActionException  { 
StringBuffer  code  =  new  StringBuf f er ( ) ; 
code . append ( super . generateFireCode ( ) ) ; 
ptolemy . actor . lib. Element sToArray  actor 

=  (ptolemy . actor . lib . ElementsToArray)  getComponent () ; 

ArrayList  args  =  new  ArrayList ( ) ; 
args.add(new  Integer (0)); 

for  (int  i  =  0;  i  <  actor . input . getwidth () ;  i++)  { 
args. set (0,  new  Integer (i)); 

code . append (_generateBlockCode ("fillArray",  args) ) ; 

} 

code . append (_generateBlockCode ("sendOutput") ) ; 
return  processCode (code . toString () ) ; 

} 


FIGURE  8.3.  The  generateFireCode()  function  of  the  ElementsToArray  helper. 

A  code  block  can  also  be  overridden.  A  code  block  (H,  N,  p)  is  overridden  by  a  code  block  (H’,  N, 
p)  given  that  H’  is  a  child  class  of  H.  This  gives  rise  to  code  block  inheritance.  Since  Ptolemy  II  actors 
are  defined  within  a  well-defined  class  hierarchy,  many  actors  inherits  fields  and  methods  from  parent 
actors.  The  codegen  helpers  mirror  the  same  class  hierarchy.  Since  code  blocks  represent  functions  of 
actors,  the  code  blocks  should  be  inherited  for  helpers  just  as  functions  are  inherited  for  actors.  Given  a 
request  for  fetching  a  code  block,  the  CodeStream  object  searches  through  all  code  template  files  of  the 
helper  and  its  ancestors,  starting  from  the  bottom  of  the  class  hierarchy.  This  mirrors  the  same  behavior 
of  invoking  an  (inherited)  function  for  an  actor. 

8.2.2  What  is  in  a  Helper  Java  Class  File? 

A  helper  java  class  is  a  valid  Java  class  that  extends  the  CodeGeneratorHelper  class.  The  Code- 
GeneratorHelper  class  implements  the  code  generation  interfaces  (ComponentCodeGenerator  and 
ActorCodeGenerator)  for  generating  code.  The  interfaces  essentially  consist  of  a  set  of  methods  that 
return  code  strings  for  specific  parts  of  the  target  program  (init(),  fire(),  wrapup(),  etc.).  The  CodeGen¬ 
eratorHelper  class  implements  the  default  behavior  for  these  methods:  each  method  fetches  and  returns 
a  code  block  (with  no  parameters)  using  the  default  code  block  name  (“initBlock”,  “fireBlock”,  “wra- 
pupBlock”,  etc.)  corresponding  to  the  method  (generateInitializeCode(),  generateFireCode(),  generate- 
WrapupCode(),  etc.).  The  child  helper  java  class  can  either  inherit  the  default  behavior  or  override  any 
method  to  fetch  multiple  code  blocks  with  non-default  names,  give  parameters  to  code  blocks,  or  do 
special  processing  on  the  returned  code  string. 

Figure  8.3  is  the  ElementsToArray  helper’s  implementation  of  the  generateFireCodeQ  method, 
found  in  $PTII/ptolemy/codegen/c/actor/lib.  This  method  uses  the  channel  number  of  the  actor  input 
port  as  the  parameter  and  fetches  the  “fillArray”  code  block  from  the  ElementsToArray. c  code  tem¬ 
plate  file  inside  the  for-loop.  It  generates  multiple  copies  of  the  "fillAarray"  code  block,  each  custom¬ 
ized  with  a  different  channel  number.  It  then  fetches  and  appends  a  different  code  block  with  the  name 
“sendOutput”  (with  no  parameters).  Finally,  it  invokes  the  processCode))  function  to  process  the 
embedded  macros  in  the  code  string.  Note  that  a  helper  java  class  needs  to  understand  the  semantics  of 
its  corresponding  actor  in  order  to  implement  these  generate  methods. 

8.2.3  The  Macro  Language 

The  macro  language  allows  helpers  to  be  written  once,  and  then  used  in  different  context  where  the 
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macros  are  expanded  and  resolved.  All  macros  in  a  code  block  are  prefixed  with  the  dollar  sign  “$” 
symbol  (i.e.  $ref(input),  $val(width),  etc.).  The  specific  macro  name  follows  immediately.  The  param¬ 
eters  to  the  macro  are  enclosed  in  parentheses  “()”■  Macros  can  be  nested  and  recursively  processed  by 
the  codegen  helper.  The  use  of  the  dollar  sign  as  prefix  is  based  on  the  assumption  that  it  is  not  a  valid 
identifier  in  the  target  language  (“$”  is  not  a  valid  identifier  in  C).  The  macro  prefix  can  be  configured 
to  correspond  to  different  target  languages.  The  macro  names  specifies  different  rules  of  text  substitu¬ 
tions  that  the  code  generator  helper  performs  to  alter  the  content  of  the  code  block.  Since  the  same  set 
of  code  blocks  may  be  shared  by  multiple  instances  of  the  helper,  the  macros  mainly  serve  the  purpose 
of  producing  unique  labels  for  different  instances  and  generate  instance-specific  port  and  parameter 
information.  The  following  is  the  documentation  of  the  set  of  macros  used  in  the  C  code  generation. 

The  Core  Macros: 

$ref(name) 

Returns  a  unique  reference  to  a  parameter  or  a  port  in  the  global  scope.  For  a  multiport,  use 
$ref(name#i)  where  i  is  the  channel  number.  During  macro  expansion,  the  name  is  replaced  by  the 
full  name  resulting  from  the  model  hierarchy. 

$ref(name,  offset) 

Returns  a  unique  reference  to  an  element  in  an  array  parameter  or  a  port  with  an  offset  in  the  global 
scope.  The  offset  must  not  be  negative.  $ref(name,  0)  is  equivalent  to  $ref(name). 

$val(parameter-name) 

Returns  the  current  value  of  the  parameter  associated  with  an  actor  in  the  simulation  model.  The 
advantage  of  not  using  $ref  macro  in  place  of  $val  is  that  no  additional  memory  needs  to  be  allo¬ 
cated.  $val  macro  is  usually  used  when  the  parameter  is  constant  during  the  execution. 

$actorSymbol(name) 

Returns  a  unique  reference  of  a  user-defined  variable  in  the  global  scope.  This  macro  is  used  to 
define  additional  variables,  for  example,  to  hold  internal  states  of  actors  between  firings.  The 
uniqueness  only  requires  that  the  name  argument  be  unique  within  the  scope  of  each  actor.  The 
helper  writer  is  responsible  for  declaring  these  variables. 

$size(name) 

If  the  given  name  represents  an  Array  Type  parameter,  it  returns  the  size  of  the  array.  If  the  given 
name  represents  a  port  of  an  actor,  it  returns  the  width  of  that  port. 


The  Type  Convert  Macros  (see  Appendix  C): 

$type() 

Returns  the  numeric  constant  that  represents  the  type  of  the  given  port  or  parameter.  The  code  gen¬ 
erator  uses  the  mapping  between  the  token  type  and  the  numeric  constant  to  look  up  the  function 
table. 

$targetType() 
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Returns  the  corresponding  target  language  type  of  the  given  typed  parameter  or  port. 

$cgtype() 

Returns  the  name  string  of  the  codegen  type  corresponding  to  a  given  typed  parameter  or  port. 

$new() 

Returns  a  new  Token  object  of  the  given  type.  This  macro  takes  at  least  one  argument:  the  codegen 
type  name  of  the  Token  with  the  value  that  are  needed  by  the  constructor  function  of  the  specific 
Token  type.  The  code  generator  keeps  track  of  the  different  types  used  through  this  macro.  For 
example,  “$new(Int(2))”  creates  an  Int  Token  variable  in  the  macro  language.  It  allocates  space  for 
the  Token;  however,  the  user  is  responsible  for  calling  the  specific  delete()  function  on  the  Token 
to  deallocate  space. 

$tokenFunc() 

Returns  a  function  call  associated  with  the  given  token.  The  function  call  is  translated  to  a  function 
pointer  in  a  two-dimensional  function  table.  The  first  index  of  the  table  is  the  different  token  types, 
and  the  second  index  is  the  different  functions  for  each  type.  The  type  of  the  given  token  is  used  to 
find  the  first  index,  and  the  name  of  the  function  is  used  to  find  the  second  index.  The  first  argu¬ 
ment  of  the  function  is  always  the  given  token,  which  acts  as  ‘this’  in  an  object-oriented  environ¬ 
ment.  The  result  is  always  another  Token.  For  example,  the  following  code  illustrates  how  a  user 
adds  two  Int  tokens  together: 

$tokenFunc ( $new ( Int (2 ) : : add ( $new ( Int ( 3 ) ) ) ) ) 

$typeFunc() 

Returns  a  function  call  associated  with  the  given  token  type.  Instead  of  using  an  associated  token, 
type  function  uses  an  associated  type  class  which  acts  similar  to  a  static  class  function.  The  follow¬ 
ing  illustrates  how  a  user  converts  an  Int  token  to  a  String  token: 

$typeFunc (TYPE  String : : convert ( $new ( Int (2 ) ) ) ) 

8.2.4  The  CountTrues  Example 

Figure  8.4  shows  a  model  in  the  synchronous  dataflow  (SDF)  domain  that  counts  the  true  values 
produced  from  the  data  source,  which  in  this  case  is  the  Pulse  actor.  The  CountTrues  actor  has  its 
blockSize  parameter  set  to  2,  which  means  it  reads  2  tokens  from  its  input  port  for  each  firing.  The 
Pulse  actor’  parameters  are  set  to  the  values  shown  in  the  figure.  When  the  model  is  simulated  in  the 
Ptolemy  II  framework,  the  produced  result  is  also  shown  in  the  figure  (the  model  is  fired  4  times 
because  the  SDFDirector’s  “iterations”  parameter  is  set  to  4). 

Let’s  look  at  the  C  code  template  files  of  the  actors  in  the  model.  Macros  are  used  extensively  in 
the  code  blocks,  and  we  will  see  how  they  are  processed  and  changed  in  the  generated  code.  Figure  8.5 
shows  the  C  code  template  files  for  the  Pulse  and  CountTrues  helpers. 

Double  clicking  on  the  StaticSchedulingCodeGenerator  icon  brings  up  the  code  generator  window. 
Clicking  the  “Generate”  button  in  the  code  generator  window  starts  the  code  generation  for  this  model. 
It  generates  a  stand-alone  C  application  program  that  executes  and  produces  the  same  result  as  the  sim¬ 
ulation  model.  Figure  8.6  shows  the  main  function  of  the  generated  C  program. 
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FIGURE  8.4.  The  model,  Pulse’s  parameters,  CountTrues’  parameter  and  the  simulation  result. 

The  generated  code  is  essentially  the  result  of  combining  the  helpers’  code  blocks.  The  $ref()  and 
$actorSymbol()  macro  are  replaced  with  unique  labels  to  represent  different  variable  references.  The 
$val()  macro  in  the  CountTrues’  “fireBlock”  code  block  is  replaced  by  the  parameter  value  of  the 
CountTrue  instance  in  the  model.  When  the  generated  C  program  is  compiled  and  executed,  the  same 
result  is  produced  as  from  the  Ptolemy  II  simulation: 

Display:  1 
Display:  1 
Display:  1 
Display:  1 

8.3  Overview  of  The  Software  Architecture 

Our  code  generation  framework  has  the  flavor  of  CG  (i.e.,  Code  Generation)  domain  and  other 
derived  domains  in  Ptolemy  Classic  [127].  However,  in  Ptolemy  Classic,  code  generation  domains  and 
simulation  domains  are  separate  and  so  are  the  actors  (called  stars  in  Ptolemy  Classic  terminology) 
used  in  these  domains.  In  ptolemy  Classic,  the  actors  in  the  simulation  domains  participate  in  simula¬ 
tion  whereas  the  corresponding  actors  in  the  code  generation  domains  participate  in  code  generation. 
Separate  domains  (simulation  vs.  code  generation)  make  it  inconvenient  to  integrate  the  model  design 
phase  with  the  code  generation  phase  and  streamline  the  whole  process.  Separate  actor  libraries  make 
it  difficult  to  maintain  a  consistent  interface  for  a  simulation  actor  and  the  corresponding  code  genera¬ 
tion  actor. 

In  Ptolemy  II,  there  are  no  separate  code  generations  domains.  Once  a  model  has  been  designed, 
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//  Pulse. c 

/***preinitBlock***/ 
int  $actorSymbol (iterationCount)  =  0; 
int  $actorSymbol (indexColCount)  =  0; 
unsigned  char  $actorSymbol (match)  =  0; 

1**1 

/***f ireBlock***/ 

if  ($actorSymbol (indexColCount)  <  $size (indexes) 

&&  $actorSymbol (iterationCount)  ==  $ref (indexes,  $actorSymbol (indexColCount) ) )  { 
$ref (output)  =  $ref (values,  $actorSymbol (indexColCount) ) ; 

$actorSymbol (match)  =  1; 

)  else  { 

$ref (output)  =  0; 

} 

if  ($actorSymbol (iterationCount)  <=  $ref (indexes,  $size (indexes)  -  1))  { 

$actorSymbol (iterationCount)  ++; 

} 

if  ($actorSymbol (match) )  { 

$actorSymbol (indexColCount)  ++; 

$actorSymbol (match)  =  0; 

} 

if  ($actorSymbol (indexColCount)  >=  $size (indexes)  &&  $val (repeat) )  { 

$actorSymbol (iterationCount)  =  0; 

$actorSymbol (indexColCount)  =  0; 

} 

1**1 

//  CountTrues.c 

/***  preinitBlock  ***/ 
int  $actorSymbol (trueCount) ; 
int  $actorSymbol (i)  ; 

1**1 

/***  fireBlock  ***/ 

$actorSymbol (trueCount)  =  0; 

for  ($actorSymbol (i)  =  0;  $actorSymbol (i)  <  $val (blockSize) ;  $actorSymbol (i) ++)  { 
if  ($ref (input,  $actorSymbol (i) ) )  { 

$actorSymbol (trueCount) ++; 

} 

} 

$ref (output)  =  $actorSymbol (trueCount) ; 

1**1 


FIGURE  8.5.  The  C  code  template  files  for  the  Pulse  and  CountTrues  helpers. 

simulated  and  verified  to  satisfy  the  given  specification  in  the  simulation  domain,  code  can  be  directly 
generated  from  the  model.  Each  helper  doesn’t  have  its  own  interface.  Instead,  it  interrogates  the  asso¬ 
ciated  actor  to  find  its  interface  (ports  and  parameters)  during  the  code  generation.  Thus  the  interface 
consistency  is  maintained  naturally.  The  generated  code,  when  executed,  should  present  the  same 
behavior  as  the  original  model.  Compared  with  the  Ptolemy  Classic  approach,  this  new  approach 
allows  the  seamless  integration  between  the  model  design  phase  and  the  code  generation  phase. 

Figure  2.12  shows  the  UML  diagram  of  key  classes  to  support  execution  in  the  ptolemy. actor 
package.  The  Executable  interface  defines  how  an  object  can  be  invoked.  The  preinitialize()  method  is 
assumed  to  be  invoked  exactly  once  during  the  lifetime  of  an  execution  of  a  model  and  before  the  type 
resolution.  The  initialize()  methods  is  assumed  to  be  invoked  once  after  the  type  resolution.  It  may  be 
invoked  again  to  reinitialize  a  (sub)model,  for  example,  in  a  modal  model  while  taking  a  transition 
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static  int  iteration  =  0; 
main  (int  argc,  char  *argv[])  { 
init  ()  ; 

/*  Static  schedule:  */ 

for  (iteration  =  0;  iteration  <  4;  iteration  ++)  { 

/*  fire  Composite  Actor  CountTrues  */ 

/*  fire  Pulse  */ 

if  (_CountTrues_Pulse_indexColCount  <  2 

&&  _CountTrues_Pulse_iterationCount  ==  Array_get (_CountTrues_Pulse_indexes_  , 
_CountTrues_Pulse_indexColCount) .payload. Int)  { 

_CountTrues_CountTrues_input [0]  =  Array_get (_CountTrues_Pulse_values_  , 
_CountTrues_Pulse_indexColCount) . payload. Boolean ; 

_CountTrues_Pulse_match  =  1 ; 

}  else  { 

_CountTrues_CountTrues_input [0]  =  0; 

} 

if  (_CountTrues_Pulse_iterationCount 

<=  Array_get (_CountTrues_Pulse_indexes_  ,2  -  1) .payload. Int)  { 
_CountTrues_Pulse_iterationCount  ++; 

) 

if  (_CountTrues_Pulse_match)  { 

_CountTrues_Pulse_indexColCount  ++; 

_CountTrues_Pulse_match  =  0; 

if  (_CountTrues_Pulse_indexColCount  >=  2  &&  true)  { 

_CountTrues_Pulse_iterationCount  =  0; 

CountTrues_Pulse_indexColCount  =  0; 


/*  fire  Pulse  */ 

//  The  code  for  the  second  firing  of  the  Pulse  actor  is  omitted  here. 


/*  fire  CountTrues  */ 

_CountTrues_CountTrues_trueCount  =  0; 

for  (_CountTrues_CountTrues_i  =  0;  _CountTrues_CountTrues_i  <  2;_CountTrues_CountTrues_i++)  { 
if  (_CountTrues_CountTrues_input [ (0  +  _CountTrues_CountTrues_i) %2] )  { 
_CountTrues_CountTrues_trueCount++; 

} 

) 

_CountTrues_Display_input [0]  =  _CountTrues_CountTrues_trueCount; 

/*  fire  Display  */ 

printf ("Display:  %d\n",  _CountTrues_Display_input [0] ) ; 


wrapup  ( ) ; 
exit  (0) ; 

} 


FIGURE  8.6.  The  main  function  of  the  generated  C  program  for  the  CountTrues  model. 
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with  the  reset  parameter  being  true.  The  prefire(),  fire(),  and  postfire()  methods  will  usually  be  invoked 
many  times,  with  each  sequence  of  method  invocations  defined  as  one  iteration.  The  stopFire()  method 
is  invoked  to  request  suspension  of  firing.  The  wrapupQ  method  will  be  invoked  exactly  once  per  exe¬ 
cution  at  the  end  of  the  execution.  The  terminate()  method  is  provided  as  a  last-resort  mechanism  to 
interrupt  execution  based  on  an  external  event. 

The  Executable  interface  is  implemented  by  the  Director  class,  and  is  extended  by  the  Actor  inter¬ 
face.  An  actor  is  an  executable  entity.  There  are  two  types  of  actors,  AtomicActor,  which  extends 
ComponentEntity,  and  CompositeActor,  which  extends  CompositeEntity.  An  AtomicActor  is  a  single 
entity,  while  a  CompositeActor  is  an  aggregation  of  actors. 

The  classes  to  support  code  generation  are  in  the  packages  under  ptolemy.  codegen  where  the 
helper  class  hierarchy  and  package  structure  parallel  those  of  regular  Ptolemy  actors.  The  counterpart 
of  the  Executable  interface  is  the  ComponentCodeGenerator  interface  and  the  ActorCodeGenerator 
interface.  These  interfaces  define  the  methods  for  generating  code  in  different  stages  corresponding  to 
what  happens  in  the  simulation. 

The  ptolemy.codegen.kemel.CodeGeneratorHelper  class  is  the  base  class  implementing  these 
interfaces  and  provides  common  features  for  all  actor  helpers.  It  gives  a  skeleton  implementation  for 
writing  a  helper  class.  Each  actor  has  a  corresponding  helper  class  for  generating  functionally  equiva¬ 
lent  code  for  this  actor  in  a  target  language.  Actors  and  their  helpers  have  the  same  names  so  that  the 
Java  reflection  mechanism  can  be  used  to  load  the  helper  for  the  corresponding  actor  during  the  code 
generation  process.  For  example,  there  is  a  Ramp  actor  in  the  package  ptolemy.actor.lib.  Correspond¬ 
ingly,  there  is  a  Ramp  helper  in  the  package  ptolemy.codegen.c.actor.lib.  Flere  c  represents  the  fact  that 
all  the  helpers  under  ptolemy.codegen.c  generate  C  code.  Assume  we  would  like  to  generate  code  for 
another  target  language  X,  the  helpers  for  generating  X  code  could  be  implemented  under 
ptolemy. codegen.x.  This  would  result  in  extendable  code  generation  framework.  Developers  could  not 
only  contribute  their  own  actors  and  helpers,  but  also  add  functionality  to  generate  code  for  a  new  tar¬ 
get  language. 

In  the  generated  code,  the  ports  of  actors  become  memory  resources  in  the  target  language,  e.g., 
global  variables  in  C  code.  A  code  template  file  can  also  define  new  variables  to  specify  the  need  for 
global  resources.  A  helper,  however,  does  not  have  the  full  knowledge  of  the  global  resources  such  as 
their  full  names  since  that  would  be  resolved  only  during  the  code  generation  process.  Therefore  a  set 
of  macros  to  access  the  global  resources,  as  defined  in  the  previous  section,  can  be  used.  The  macros 
are  resolved  and  expanded  according  to  the  context  in  a  specific  model. 

The  above  approach  to  create  actor  helpers  achieves  modularity,  maintainability,  portability  and 
efficiency  in  code  generation.  The  target  code  for  each  helper  can  be  verified  for  correctness  and  opti¬ 
mized  for  efficiency  individually.  The  code  for  the  whole  model  is  assembled  from  the  target  code  for 
the  contained  actors  plus  some  extra  code  serving  as  glue  logic. 

To  generate  code  for  hierarchically  composed  models,  helpers  for  composite  actors  are  also  cre¬ 
ated.  For  example,  the  most  commonly  used  composite  actor  is  TypedCompositeActor  in  the  package 
ptolemy. actor.  A  helper  with  the  same  name  is  created  in  the  package  ptolemy.codegen.c. actor.  The 
main  function  of  this  helper  is  to  delegate  the  code  generation  for  the  associated  composite  actor  to  the 
helper  of  the  local  director  (discussed  next)  or  the  helpers  of  the  actors  contained  by  the  composite 
actor.  Other  composite  actors  include  ModalModel,  Refinement,  etc.  and  the  corresponding  helpers  are 
created  for  each  of  them  (see  more  details  in  the  Domains  section). 

In  Ptolemy  II,  a  director  governs  the  execution  of  a  composite  actor  and  thus  each  director  needs  a 
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helper  to  generate  the  code  for  the  containing  composite  actor  so  that  the  generated  code  is  function¬ 
ally  equivalent  to  the  composite  actor.  Currently  we  can  generate  code  for  the  domains  where  actor 
executions  can  be  statically  scheduled  such  as  the  SDF  and  HDF  domains.  The  involved  directors 
include  SDF  director,  F1DF  director,  F1DFFSM  director,  MultirateFSM  director  and  FSM  director. 
Indeed  there  is  a  helper  for  each  director  with  the  same  class  name  and  located  in  the  corresponding 
package  under  ptolemy. codegen.  These  director  helpers  generate  code  according  to  the  Models  of 
Computation  (MoCs)  they  represent.  They  concatenate  target  code  blocks  with  the  help  of  a  scheduler, 
allocate  memory  according  to  the  calculated  buffer  sizes,  and  also  generate  the  target  code  for  the  glue 
logic  specific  to  their  MoCs.  The  details  will  be  presented  in  the  next  section. 

Finally  the  StaticSchedulingCodeGenerator  class  is  used  to  orchestrate  the  whole  code  generation 
process.  An  instance  of  this  class  is  contained  by  the  top  level  composite  actor  as  an  attribute  and  inter¬ 
acts  with  it  directly.  Therefore  the  code  generation  starts  at  the  top  level  composite  actor  and  the  code 
for  the  whole  model  is  generated  hierarchically,  much  similar  to  how  a  model  is  simulated  in  Ptolemy 
II  environment. 

The  flow  chart  in  figure  8.7  sketches  the  whole  code  generation  process  step  by  step.  The  details  of 
some  steps  are  MoC-specific  and  will  be  presented  in  the  next  section.  Notice  that  the  steps  outlined  do 
not  necessarily  follow  the  same  order  the  generated  codes  are  assembled  together.  For  example,  only 
those  parameters  that  are  referenced  during  the  code  generation  will  be  defined.  Therefore  those  defi¬ 
nitions  will  be  generated  last  but  attached  to  variable  definition  segment  at  the  beginning  of  the  gener¬ 
ated  code. 

Readers  could  find  out  by  now  that  the  helper  based  code  generation  framework  functions  as  a 
coordination  language  for  the  target  code.  It  not  only  leverages  the  huge  legacy  code  repository,  but 
also  takes  advantage  of  many  years  and  many  researchers’  work  on  compiler  optimization  techniques 
for  the  target  language.  It  is  accessible  to  a  huge  base  of  programmers.  Oftentimes  a  new  language  fails 
to  catch  on  not  because  it  is  technically  flawed,  but  because  it  is  very  difficult  to  penetrate  the  barrier 
established  by  the  languages  already  in  widespread  use.  With  the  use  of  the  helper  class  combined  with 
target  code  template  written  in  a  language  programmers  are  familiar  with,  there  is  much  less  of  a  learn¬ 
ing  curve  to  use  our  design  and  codegen  environment. 

8.4  Domains 

8.4.1  SDF 

The  synchronous  dataflow  (SDF)  domain  is  one  of  the  most  mature  domains  in  Ptolemy  II.  The 
details  of  this  domain  can  be  found  in  Volume  3.  Under  the  SDF  domain,  the  execution  order  of  actors 
is  statically  determined  prior  to  execution.  This  opens  the  door  for  generating  some  very  efficient  code. 
In  fact,  the  SDF  software  synthesis  has  been  studied  extensively.  One  book  [18],  several  Ph.D.  disser¬ 
tations  [17][1 13]  and  numerous  papers  have  been  written  about  it.  Many  optimization  techniques  have 
been  designed  according  to  different  criteria  such  as  minimization  of  program  size,  buffer  size 
[  1 8] [  1 14],  or  actor  activation  rate  [134].  Hardware  synthesis  from  SDF  specification  has  also  been 
studied  by  many  researchers,  e.g.,  see  [63]. 

In  parallel  with  the  software  architecture  in  the  simulation  domain,  the  helper  for  the  SDFDirector 
is  inherited  from  the  helper  for  the  Static  SchedulingDirector,  which  is  further  inherited  from  the  helper 
for  the  Director.  The  helper  for  the  Static  SchedulingDirector  is  responsible  for  generating  the  target 
code  semantically  equivalent  to  a  predetermined  sequence  of  actor  firings  in  one  complete  static 
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These  files  include,  e.g.,  math.h,  stdio.h, 
needed  by  some  actors  in  their  generated  code. 


The  shared  code  includes  macro  defini¬ 
tions,  new  data  type  definitions,  function  defi¬ 
nitions,  etc. 


These  are  variables  that  are  directly  modi¬ 
fied  by  actors,  e.g.,  during  mode  transitions. 


New  variables  other  than  those  resulting 
from  ports  and  parameters  could  be  defined 
here. 


These  offset  variables  are  used  to  record 
the  circular  buffer  positions  during  code  gener¬ 
ation. 


Variables  are  initialized  here.  Make  sure 
the  code  generated  here  can  be  executed  multi¬ 
ple  times, e.g., after  a  reset  transition  in  an  FSM. 


The  code  generated  here  performs  major 
functions,  corresponding  to  actor  firings. 


The  code  generated  here  does  some  wra- 
pup  work,  e.g.,  closing  open  files. 


These  variables  are  those  resulting  from 
ports  and  parameters.  Some  can  only  be  deter¬ 
mined  towards  the  end  of  the  code  generation. 


The  code  generated  here  is  necessary  to 
support  dynamic  type  conversion. 


FIGURE  8.7.  The  flow  chart  of  the  code  generation  process. 


8-182 


Ptolemy  II 


Code  Generation 


schedule.  The  helper  for  the  SDFDirector  utilizes  the  SDFScheduler  implemented  in  the  current  SDF 
domain,  but  the  framework  allows  to  plug  in  any  optimizing  scheduler  and  then  generates  the  corre¬ 
sponding  code  for  that  scheduler. 

There  are  several  points  to  notice  in  the  implementation  of  the  helper  for  the  SDFDirector.  First, 
the  minimum  buffer  size  of  each  receiver  is  determined  by  the  SDFScheduler  and  the  helper  for  the 
SDFDirector  uses  that  information  to  determine  the  size  for  the  buffer  array  in  the  generated  code.  For 
a  minimum  buffer  size  of  one,  only  a  simple  variable  instead  of  an  array  is  used.  For  a  multiport,  when 
the  minimum  buffer  size  of  each  receiver  contained  by  the  multiport  is  one,  one  dimensional  array  is 
used  where  each  element  of  the  array  corresponds  to  a  different  receiver  contained  by  the  multiport; 
when  the  minimum  buffer  size  of  any  receiver  contained  by  the  multiport  exceeds  one,  a  general  two 
dimensional  array  is  used.  Second,  the  firing  code  for  each  actor  is  inlined  by  default,  i.e.,  during  the 
code  generation,  the  firing  code  of  each  actor  is  expanded  whenever  the  actor  needs  to  be  fired  as  dic¬ 
tated  by  the  schedule,  resulting  in  a  monolithic  body  of  the  code  for  the  whole  model.  When  the  inline 
option  is  switched  off,  the  firing  code  for  each  actor  is  wrapped  inside  its  own  function  and  the  gener¬ 
ated  code  calls  these  functions  in  the  order  dictated  by  the  schedule.  The  inline  version  may  run  faster 
without  the  call-return  overhead.  The  non-inline  version  may  reduce  the  memory  footprint  of  the  gen¬ 
erated  code  when  there  is  no  single  appearance  schedule  (a  single  appearance  schedule  is  a  looped 
schedule  where  each  actor  shows  up  at  most  once  [18])  or  when  the  reduction  of  the  buffer  size  using 
multiple  appearance  schedule  is  more  effective  than  the  reduction  of  program  size  using  single  appear¬ 
ance  schedule.  We  are  experimenting  with  different  options  to  generate  code  with  better  performance 
or  better  (smaller)  size. 

The  code  generation  framework  has  been  under  active  development  and  we  can  generate  code  for 
a  lot  of  models.  But  still  we  cannot  generate  code  for  all  SDF  models,  mostly  due  to  the  lack  of  helpers 
for  the  actors  contained  in  these  models,  but  sometimes  due  to  other  reasons  such  as  the  lack  of  code¬ 
gen  support  for  the  data  types  used  in  the  models.  We  are  continuously  adding  more  helpers  and  more 
functionalities. 

Several  interesting  demos  for  the  SDF  code  generation  are  presented  next.  Figure  8.8  shows  the 
Butterfly  demo  in  $PTII/ptolemy/domains/sdf/demo/Butterfly.  During  code  generation,  the  helper  for 
the  Expression  actor  uses  a  PtParser  to  parse  the  Ptolemy  expression  specified  in  the  actor  and  then 
uses  a  CParseTreeCodeGenerator  to  generate  the  corresponding  C  code.  The  C  code  generated  by  the 
helper  for  the  XYPlotter  actor  invokes  JVM  (Java  Virtual  Machine)  through  JNI  (Java  Native  Inter¬ 
face)  and  then  calls  the  methods  of  the  classes  in  the  plot  package  for  two-dimensional  graphical  dis¬ 
play.  Notice  the  generated  C  code  does  not  need  the  Ptolemy  framework  to  run.  It  merely  uses  the  plot 
utilities  (which  happen  to  be  written  in  Java)  for  displaying  data.  One  could  write  a  different  helper  for 
the  XYPlotter  actor  to  generate  the  customized  code  for  displaying  data  in  a  specific  target  system. 

The  Case  demo  in  $PTII/ptolemy/actor/lib/hoc/demo/Case  shows  a  model  with  a  switch/case-type 
structure.  The  interesting  part  about  this  model  is  the  use  of  a  Case  actor  controlled  by  a  CaseDirector. 
Correspondingly,  there  is  a  helper  for  the  Case  actor  and  a  helper  for  the  CaseDirector  for  code  gener¬ 
ation. 

8.4.2  FSM 

Finite  state  machines  (FSMs)  have  been  the  subject  of  a  long  history  of  research  work.  In  ptolemy 
II,  an  FSM  actor  serves  two  purposes:  traditional  FSM  modeling  and  modal  models.  In  traditional 
FSM  modeling,  an  FSM  actor  reacts  to  the  inputs  by  making  state  transitions  and  sending  tokens  to  the 
output  ports  like  a  regular  Ptolemy  actor.  In  the  *charts  formalism  with  modal  models  [47],  modes  are 


Heterogeneous  Concurrent  Modeling  and  Design 


8-183 


Code  Generation 


SDF  Director  StaticSchedulingCodeGenerator 


Double  click  to 
generate  code. 

This  model  traces  an  elaborate  curve 

called  the  butterfly  curve.  It  was  described  by  T.  Fay, 

American  Mathematical  Monthly,  96(5),  May,  1989. 


Expression2 


The  expression  in  the  Expression  actor  is 

-2.0*cos(4.0'ramp)  +  exp(cos(ramp))  +  (sin(ramp/12.0)  *  (sin(ramp/12.0))M). 
Author:  Edward  A.  Lee 


FIGURE  8.8.  SDF  Code  generation  for  the  Butterfly  demo. 

represented  by  states  of  an  FSM  actor  that  controls  mode  switching.  Each  mode  has  one  or  more 
refinements  that  specify  the  behavior  of  the  mode.  A  modal  model  is  constructed  in  a  ModalModel 
actor  having  the  FSM  director  as  local  director.  The  ModalModel  actor  contains  a  ModalController 
(essentially  an  FSM  actor)  and  a  set  of  Refinement  actors  that  model  the  refinements  associated  with 
states  and  possibly  a  set  of  TransitionRefinement  actors  that  model  the  refinements  associated  with 
transitions.  The  FSM  director  mediates  the  interaction  with  the  outside  domain,  and  coordinates  the 
execution  of  the  refinements  with  the  ModalController.  The  details  of  this  domain  can  be  found  in  Vol¬ 
ume  3. 

Correspondingly,  the  helper  for  the  FSMActor  is  designed  to  generate  appropriate  target  code 
according  to  its  context.  When  the  FSMActor  is  used  as  a  standalone  actor,  the  helper  generates  the 
code  for  all  outgoing  transitions  for  each  state;  when  it  is  used  as  a  ModalController  in  a  ModalModel, 
the  helper  generates  the  code  for  preemptive  transitions  and  the  code  for  non-preemptive  transitions 
separately.  Regardless  of  the  context,  for  each  state  and  each  outgoing  transition  from  that  state,  the 
generated  code  follows  exactly  the  same  execution  sequence  as  in  the  original  model— first,  the  guard 
expression  is  translated  into  the  target  code  using  a  ParseTreeCodeGenerator;  then  all  the  choice 
actions  contained  by  the  transition  are  transformed  into  the  target  code;  if  there  is  any  refinement  asso¬ 
ciated  with  the  transition  (represented  by  a  TransitionRefinement  actor  which  is  different  from  a 
Refinement  actor  associated  with  a  state),  the  corresponding  code  for  the  refinement  is  generated;  next, 
all  the  commit  actions  contained  by  the  transition  are  transformed  into  the  target  code;  the  code  for 
updating  new  current  state  follows;  finally  the  code  for  (re)initializing  the  refinement  associated  with 
the  new  state  is  generated  when  the  reset  parameter  of  the  transition  is  true. 

The  internal  execution  of  a  ModalModel  is  controlled  by  a  local  director,  which  can  be  an  FSMDi- 
rector,  a  MultirateFSMDirector,  or  an  FIDFFSMDirector.  A  user  can  choose  a  director  for  a  ModalM¬ 
odel.  Usually  only  one  specific  director  makes  sense  for  the  behavior  the  user  wants  for  the  model.  For 
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example,  an  FSMDirector  is  used  when  the  rate  for  all  the  ports  of  a  ModalModel  is  1  and  the 
ModalModel  tries  a  transition  from  the  current  state  during  every  firing  of  the  ModalModel.  A  Multi- 
rateFSMDirector  is  inherited  from  FSMDirector  to  model  multirate  behavior.  To  guarantee  static 
schedulability  under  SDF,  all  state  refinements  must  present  the  same  rate  to  the  outside  for  all  the 
ports  mirrored  to  the  same  port  in  the  ModalModel.  In  addition,  a  MultirateFSMDirector  makes  only 
non-preemptive  transitions  so  that  the  refinement  for  the  current  state  gets  fired  before  trying  a  transi¬ 
tion  and  tokens  are  consumed  from  input  ports  and  sent  to  output  ports  according  to  the  rate  of  each 
port.  If  the  refinement  associated  with  different  state  presents  a  different  rate,  an  HDFFSMDirector 
must  be  used.  It  is  further  inherited  from  MultirateFSMDirector  and  only  tries  a  transition  after  the 
whole  model  finishes  the  execution  of  one  complete  schedule.  Together  with  HDFDirector,  it  imple¬ 
ments  the  HDF  domain  (see  section  8.4.3).  No  matter  which  FSM  director  the  user  chooses,  the  corre¬ 
sponding  helper  generates  the  target  code  which  preserves  the  original  model  behavior. 

To  support  code  generation  for  modal  models,  four  helpers  are  also  created  including  ModalCon- 
troller,  ModalModel,  Refinement  and  TransitionRefinement.  They  are  inherited  from  the  helpers  for 
FSMActor  or  TypedCompositeActor  but  add  no  new  functionality  because  their  associated  actor 
classes  are  used  to  build  modal  model  structures  (such  as  mirroring  ports).  These  helpers  inherit  their 
functionality  from  their  base  classes. 

The  VariableScope  inner  class  in  CodeGeneratorHelper  handles  code  generation  for  expressions 
contained  by  parameters.  To  support  code  generation  for  modal  models,  the  derived  PortScope  inner 
class  in  the  helper  for  the  FSMActor  handles  code  generation  for  guard  expressions  with  multi-channel 
and  multi-rate  syntax.  Both  inner  classes  would  expand  any  expression  recursively  until  any  variable 
in  the  expression  is  either  a  constant  (in  this  case  the  constant  is  substituted  for  the  variable)  or  a  mod¬ 
ifiable  variable,  e.g.,  modified  in  a  mode  transition  or  in  a  SetVariable  actor  (in  this  case  a  variable 
which  is  defined  at  the  beginning  of  the  generated  code  is  used). 

Several  interesting  demos  for  the  FSM  code  generation  are  presented  next.  The  Blending  demo  in 
$PTII/ptolemy/domains/fsm/demo/Blending  models  a  controller  with  two  major  control  modes  and 
two  transition  modes.  Each  major  mode  has  one  Refinement.  Each  transition  mode  has  three  Refine¬ 
ments.  Some  Refinements  are  shared  by  different  modes.  After  the  controller  is  designed  and  simu¬ 
lated  to  meet  the  given  specification  in  the  Ptolemy  environment,  the  generated  C  code  can  then  run  on 
some  embedded  platform. 

The  Modal  Binary  Symmetric  Channel  demo  in  $PTII/ptolemy/domains/fsm/demo/ModalBSC 
models  a  channel  with  two  states,  each  with  different  probabilities  of  error.  The  model  not  only  has 
Refinement  associated  with  state,  but  also  has  TransitionRefinement  associated  with  transition.  These 
modeling  constructs  are  automatically  realized  in  the  generated  code. 

8.4.3  HDF 

The  Heterochronous  Dataflow  (HDF)  domain  extends  the  SDF  domain  by  allowing  changes  in 
port  rates  (called  rate  signature)  between  iterations  of  the  whole  model.  Within  each  iteration,  rate  sig¬ 
natures  are  fixed  and  an  HDF  model  behaves  like  an  SDF  model.  This  guarantees  that  a  schedule  can 
be  completely  executed.  Between  iterations,  any  modal  model  can  make  a  state  transition  and  therefore 
derives  its  rate  signature  from  the  refinement  associated  with  the  new  state.  The  HDF  domain  recom¬ 
putes  the  schedule  when  necessary.  The  details  of  this  domain  can  be  found  in  Volume  3. 

Since  it’s  expensive  to  compute  the  schedule  during  the  run  time,  all  possible  schedules  are  pre¬ 
computed  during  the  compilation  time  (i.e.,  code  generation  time).  The  structure  of  the  generated  code 
is  hard-coded  in  such  a  way  that  it  reflects  all  possible  execution  paths  for  different  schedules. 
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Since  an  HDF  model  can  have  arbitrary  levels  of  hierarchy,  there  must  be  a  systematic  way  to  find 
out  the  number  of  schedules  and  enumerate  all  schedules  for  any  HDF  model.  The  approach  taken  here 
uses  the  following  definition. 

For  each  opaque  actor  (i.e.,  atomic  actor  or  opaque  composite  actor),  let  N  be  the  number  of  con¬ 
figurations  of  this  actor.  For  each  configuration  of  the  actor,  it  has  a  corresponding  local  SDF  schedule. 
(An  atomic  actor  has  a  degenerate  form  of  local  SDF  schedule:  fire  itself  once.) 

Let  r..  be  the  rate  of  the  j  th  port  of  this  actor  in  the  i  th  configuration,  where  i  =  0,  1 , 

j  =  0, . . .,  P-  1  and  P  is  the  number  of  ports  of  this  actor. 

Let  Ri  =  { 0, ....  P-  I  (  be  the  rate  signature  of  this  actor  in  the  i  th  configuration. 

During  code  generation,  N  and  R:,  i  =  0,  ...,7V-  1  for  each  opaque  actor  are  derived  in  a  recursive 
bottom-up  fashion: 

1.  Atomic  actor.  N  =  1 ,  R0  -  the  rate  signature  of  the  atomic  actor. 

2.  Composite  actor  with  a  local  SDFDirector.  N  =  1 ,  R0  =  the  rate  signature  of  the  composite  actor 
inferred  from  the  local  SDF  schedule.  Precondition :  each  contained  actor  has  only  one  rate  signa¬ 
ture  (i.e.,  one  configuration). 

3.  Modal  model  with  a  local  FSMDirector.  N  =  1 ,  R0  =  {  r0j }  where  r0j  =  1  for  all  j .  Precondition : 
all  the  refinements  have  only  one  rate  signature  and  all  the  port  rates  are  1 . 

4.  Modal  model  with  a  local  MultirateFSMDirector.  N  =  1 ,  R0  =  the  rate  signature  of  any  refine¬ 
ment.  Precondition :  all  the  refinements  have  only  one  and  same  rate  signature. 


5. 


M-  1 


Modal  model  with  a  local  HDFFSMDirector.  N  =  ^  at  where  AT  is  the  number  of  configura- 

7  =  0 

tions  of  the  j  th  refinement,  M  is  the  number  of  refinements.  For  i  =  0, ...,  N- 1 ,  Rt  =  the  rate  sig- 

k- i 

nature  of  the  k  th  refinement  in  its  q  th  configuration,  where  k  is  derived  from  i  -  ^  /V)  >  0  and 

7  =  0 


k 


k-\ 


i-  YjNj<° ,  q  is  derived  from  q 

7  =  0 


7  =  0 


M-  1 

6.  Composite  actor  with  a  local  HDFDirector:  N  =  ]^[  Nj  where  Nj  is  the  number  of  configurations 

7  =  0 

of  the  y  th  contained  actor,  M  is  the  number  of  contained  actors.  For  i  =  0,  I  ,  R;  =  the  rate 
signature  of  the  composite  actor  inferred  from  the  local  SDF  schedule  when  the  j  th  contained 
actor,  for  j  =  0,  1 ,  presents  its  rate  signature  in  its  k, th  configuration  ,  where  kj  is  derived 

M- 1  \ 

from  7  =  £  kj  fl  N,  ■ 

7  =  (A  q=j  + 1  ' 

The  above  computation  is  performed  in  the  generatePreinitializeCode()  method  of  each  director 
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helper.  After  the  computation  is  complete,  the  helper  for  each  actor  has  recorded  its  number  of  config¬ 
urations,  the  rate  signature  presented  to  the  outside  in  each  configuration,  and  the  local  SDF  schedule 
in  each  configuration.  During  this  step,  the  maximum  capacity  of  each  receiver  under  all  schedules  is 
also  recorded,  except  the  receivers  of  modal  controllers,  whose  maximum  capacity  must  be  computed 
in  the  next  step,  because  a  modal  controller  may  potentially  access  all  received  data  during  one  global 
iteration  (of  the  whole  model)  and  the  number  of  times  the  modal  model  containing  the  modal  control¬ 
ler  is  fired  in  one  global  iteration  is  not  available  in  the  bottom-up  traversal. 

The  next  step  is  to  traverse  the  model  structure  in  a  top-down  fashion  in  the  createOffsetVari- 
ablesIfNeeded()  method.  The  helper  for  each  composite  actor  contains  an  integer  array: 

firingsPerGloballteration,  the  length  of  which  is  equal  to  the  number  of  configurations  of  the  actor. 
Each  element  in  the  array  represents  the  maximum  number  of  times  the  actor  is  fired  in  each  configu¬ 
ration  during  one  global  iteration.  It  is  computed  in  the  following  way.  Each  element  of  the  array  is  ini¬ 
tialized  to  be  1  for  the  top  composite  actor.  If  a  composite  actor  is  internally  controlled  by  an 
HDFDirector,  each  contained  actor  derives  its  firingsPerGloballteration  from  the 
firingsPerGloballteration  of  its  container  together  with  the  number  of  times  this  actor  is  fired  in  a 
local  SDF  schedule.  If  a  composite  actor  is  internally  controlled  by  an  HDFFSMDirector,  each  con¬ 
tained  refinement  derives  its  firingsPerGloballteration  directly  from  the  firingsPerGloballteration  of 
its  container.  Imagine  a  controller  receives  a  large  number  of  tokens  in  one  global  iteration  and  corre¬ 
spondingly  a  large  chunk  of  memory  must  be  allocated  in  the  generated  code.  One  way  to  get  around 
this  is  to  directly  analyze  the  guard  expression  and  find  out  how  far  back  the  controller  needs  to  access 
the  received  tokens  and  only  allocate  that  amount  of  memory.  This  should  be  easy  to  do  if  constant 
array  indexes  are  used  to  access  the  received  tokens.  However,  if  that  is  not  the  case,  then  the  optimiz¬ 
ing  approach  might  not  work.  The  current  implementation  allocates  the  maximum  amount  of  memory 
ever  needed  in  one  global  iteration,  therefore  correctness  is  guaranteed. 

Upon  completing  the  previous  two  traversals,  the  HDF  model  has  been  analyzed  and  it’s  ready  to 
generate  the  target  code.  The  code  for  variable  declarations  and  initializations  is  generated  as  usual. 
The  bulk  of  the  code  is  generated  in  the  generateFireCode()  method.  The  interesting  part  is  where  the 
code  for  making  mode  transitions  is  generated.  In  a  modal  model  containing  a  MultirateFSMDirector 
or  an  FSMDirector,  the  mode  transition  code  is  generated  in  the  generateFireCode()  method  and  there¬ 
fore  executed  at  the  end  of  each  firing  of  the  modal  model.  In  a  modal  model  containing  an  HDFFSM¬ 
Director,  only  the  code  for  setting  some  “fired”  boolean  variables  is  generated  in  the 
generateFireCode()  method;  the  actual  code  for  making  mode  transitions  is  generated  in  the  generate- 
ModeTransitionCode()  method  and  appended  after  the  code  corresponding  to  one  global  iteration. 
When  the  generated  code  is  executed,  those  “fired”  variables  essentially  record  a  trace  about  what  part 
of  the  model  is  executed  in  each  global  iteration.  The  mode  transition  phase  follows  this  trace  and  exe¬ 
cutes  the  code  for  making  mode  transitions  and  updating  the  variables  representing  the  current  state 
and  the  current  configuration. 

Several  interesting  demos  for  the  HDF  code  generation  are  presented  next.  The  Merge  demo  in 
$PTII/ptolemy/domains/hdf/demo/Merge  shows  an  interesting  way  to  merge  two  increasing  sequences 
of  numbers  into  one  increasing  sequence.  The  AdaptiveCoding  demo  in  $PTII/ptolemy/domains/hdf/ 
demo/AdaptiveCoding  shows  the  modeling  of  two  modes  of  Hamming  codec,  a  (7,  4)  Hamming  code 
and  a  (3,1)  Hamming  code.  The  model  switches  between  the  two  coding/decoding  schemes  depending 
on  the  channel  condition. 
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Appendix  C:  CodeStream  and  CodeGen  Types 

C.l  The  CodeStream  Mechanism 

C.l.l  Code  Block  Structure 

For  a  helper,  a  code  block  is  uniquely  defined  by  its  signature  which  consists  of  its  code  block 
name  and  the  number  of  parameters  it  takes.  A  proper  code  block  should  have  the  following  grammar: 

/***  CodeBlockName  [ ($parameterl,  $parameter2,  ...)]  ***/ 

CodeBlockBody 

/**/ 


Parameterized  code  blocks  can  contain  parameters  which  the  user  can  specify.  Parameter  substitu¬ 
tion  syntax  is  straight-forward  string  pattern  substitution,  so  the  user  is  responsible  for  declaring 
unique  parameter  names.  For  example,  a  code  block  is  declared  to  be  the  following: 

/***  initBlock  ($arg)  ***/ 
if  ($ref (input)  !=  $arg)  { 

$ref (output)  =  $arg; 


/**/ 

If  the  helper  invokes  the  appendCodeBlock()  method  with  a  single  parameter,  which  is  the  integer 

3, 

ArrayList  args  =  new  ArrayListO; 
args . add (Integer . toString (3) )  ; 
appendCodeBlock ("initBlock",  args) ; 

then  after  parameter  substitution,  the  code  block  would  become: 

if  ($ref (input)  !=  3)  { 

$ref (output)  =  3; 

} 

C.1.2  Overriding  and  Overloading 

CodeStream  supports  overriding  superclass  code  blocks  with  same  signature.  However,  it  does  not 
support  call  to  superclass  code  blocks  that  have  been  overridden  (i.e.,  there  is  not  a  function  call  like 
super()),  so  far.  It  also  supports  overloading  code  blocks  with  different  number  of  parameters. 

C.2  Type  Conversion:  CodeGen  Types 

Ptolemy  II  supports  a  variety  of  types  that  are  different  from  the  target  language.  It  sometimes 
dynamically  converts  tokens  in  the  execution  of  the  model.  Thus,  the  code  generator  has  to  deal  with 
some  type  conversion  issues.  First,  it  has  to  generate  code  that  represents  the  different  PTII  token  types 
and  functionality  of  the  tokens  in  the  target  language.  Second,  it  has  to  be  able  to  convert  one  type  to 
another  that  is  higher  in  the  type  lattice.  Thirdly,  the  code  generator  has  to  know  where  type  conver¬ 
sions  need  to  occur  in  order  to  generate  compilable  code  and  code  that  produces  the  correct  result. 

For  each  Ptolemy  token  type,  there  is  an  associated  codegen  Token  type.  In  the  $PTII/ptolemy/ 
codegen/kemePtype  directory,  there  is  a  target-language  specific  file  which  contains  functionality  code 
for  each  Ptolemy  type.  The  code  generator  uses  the  code  stream  mechanism  to  harvest  the  code  blocks 
in  these  files.  E.g.  The  Int.c  file  contains  code  to  operate  on  an  integer  token. 
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/***negateBlock***/ 

Token  Int_negate (Token  this,  ...)  { 

this .payload. Int  =  -this .payload. Int; 
return  this; 

} 

/**/ 

The  code  generator  handles  three  kinds  of  type  conversion.  The  first  case  is  converting  between 
primitive  (non-Token)  types.  The  target  languages  often  support  some  of  the  Ptolemy  types  as  primi¬ 
tive  types.  The  code  generator  can  take  advantage  of  the  language  constructs  to  avoid  storage  and  pro¬ 
cessing  time  overhead  by  using  these  primitive  types.  For  example,  the  c  code  generator  uses  int, 
double  and  char  array  (char*)  to  represent  the  Ptolemy  int,  double  and  string  types.  The  c  code  genera¬ 
tor  generates  functions  to  convert  int  and  double  to  char*  type  (because  string  is  higher  than  int  and 
double  in  the  type  lattice). 

char*  InttoString  (int  i)  { 

char*  string  =  (char*)  malloc (sizeof (char)  *  12); 
sprintf ( (char*)  string,  "%d",  i); 
return  string; 

} 

The  second  case  is  to  upgrade  a  primitive  type  to  a  Token  type.  This  happens  often  in  a  multiport 
connection  where  the  sink  port  (multiport)  is  resolved  to  type  ‘general’  and  the  source  ports  are 
resolved  to  concrete  types,  like  int,  string,  etc.  The  code  generator  takes  care  of  this  by  using  the 
$new()  macro  to  create  a  new  Token  for  the  given  primitive  value  (there  is  an  associated  codegen 
Token  type  for  each  Ptolemy  type  including  the  primitive  type). 

The  third  case  is  to  convert  between  different  Token  types.  The  functionality  code  for  each  code¬ 
gen  type  has  a  convert  function  that  converts  the  given  token.  For  example,  in  $PTII/ptolemy/codegen/ 
kemel/type/String.c,  the  convertBlock  looks  like1: 

/***convertBlock***/ 

Token  String_convert (Token  token,  ...)  { 
char*  stringPointer; 

switch  (token. type)  { 

#ifdef  TYPE_Boolean 
case  TYPE_Boolean : 

stringPointer  =  BooleantoString (token .payload. Boolean) ; 
break; 

#endif 

#ifdef  TYPE_Int 
case  TYPE_Int: 

stringPointer  =  InttoString (token .payload. Int) ; 
break; 

#endif 

#ifdef  TYPE_Double 
case  TYPE_Double: 

stringPointer  =  DoubletoString (token .payload. Double) ; 
break; 

#endif 

default ; 

//  FIXME;  not  finished 


1.  The  user  should  use  the  $typeFunc()  (rather  than  $tokenFunc())  macro  to  call  the  convert()  function  because 
convert))  is  a  static/class  function.  If  the  $tokenFunc()  macro  is  used,  the  convert  function  of  the  given  token’s 
type  is  invoked  rather  than  the  String  type.  Since  the  token  is,  of  course,  the  same  type  of  its  own  type;  thus,  no 
conversion  occurs. 
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fprintf (stderr,  "String_convert ( ) : 

Conversion  from  an  unsupported  type.  (%d)\n",  token. type); 

break; 

} 

token .payload. String  =  stringPointer; 
token. type  =  TYPE_String; 
return  token; 

} 

/**/ 

C.3  Examples 

C.3.1  How  to  write  the  helper  for  a  polymorphic  actor  (AddSubtract) 

The  following  is  the  code  generation  fire  method  in  the  AddSubtract  helper  (AddSubtract.java): 

public  String  generateFireCode ( )  throws  IllegalActionException  { 
super . generateFireCode ( ) ; 

ptolemy. actor . lib. AddSubtract  actor  = 

(ptolemy. actor . lib .AddSubtract)  getComponent () ; 

Type  type  =  actor . output . getType () ; 

boolean  minusOnly  =  actor .plus . getwidth ( )  ==  0; 

ArrayList  args  =  new  ArrayListO; 
args.add(new  Integer (0)); 

if  (type  ==  BaseType. STRING)  { 

_codeStream. appendCodeBlock ( "StringPreFireBlock" ) ; 
for  (int  i  =  0;  i  <  actor . plus . getwidth () ;  i++)  { 
args. set (0,  new  Integer (i)); 

_codeStream. appendCodeBlock ( "StringLengthBlock" ,  args) ; 

} 

_codeStream. appendCodeBlock ( "StringAllocBlock" ) ; 

}  else  { 

String  blockType  =  isPrimitive (type)  ?  " "  :  "Token"; 

String  blockPort  =  (minusOnly)  ?  "Minus"  : 

_codeStream. appendCodeBlock (blockType  +  blockPort  +  "PreFireBlock") ; 

} 


String  blockType  =  isPrimitive (type)  ?  codeGenType (type)  ;  "Token"; 

for  (int  1=1;  i  <  actor . plus . getwidth () ;  i++)  { 
args. set (0,  new  Integer  ( i ) ) ; 

_ codeStream. appendCodeBlock (blockType  +  "AddBlock",  args); 

} 


for  (int  i  =  minusOnly  ?  1  ;  0;  i  <  actor .minus . getwidth () ;  i++)  { 
args. set (0,  new  Integer  ( i ) ) ; 

_ codeStream. appendCodeBlock (blockType  +  "MinusBlock",  args); 

} 


_codeStream. appendCodeBlock ("PostFireBlock" ) ; 
return  processCode (_codeStream. toString () )  ; 


These  are  the  corresponding  code  blocks  in  the  code  template  (AddSubtract. c): 

/***PreFireBlock***/ 

SactorSymbol (result)  =  $ref (plus#0) ; 

/**/ 
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/***MinUsPreFireBl0Ck***/ 

$actorSymbol (result)  =  -$ref (minus#0) ; 

/**/ 

/***TokenPreFireBlock***/ 

$actorSymbol (result)  =  $ref (plus#0) ; 

/**/ 

/***TokenMinusPreFireBlock***/ 

$actorSymbol  (result)  =  $tokenFunc  ($ref  (minus#0)  :  .-negate  ())  ; 
/**/ 


/***IntAddBlock ($channel) ***/ 

$actorSymbol (result)  +=  $ref (plus#$channel) ; 
/**/ 


/***IntMinusBlock ($channel) ***/ 

$actorSymbol (result)  -=  $ref (minus#$channel) ; 
/**/ 


/***DoubleAddBlock ($channel) ***/ 

$actorSymbol (result)  +=  $ref (plus#$channel) ; 
/**/ 


/***DoubleMinusBlock ($channel) ***/ 
$actorSymbol (result)  -=  $ref (minus#$channel) ; 
/**/ 


/***BooleanAddBlock ($channel) ***/ 
$actorSymbol (result)  |=  $ref (plus#$channel) ; 
/**/ 


/***StringPreFireBlock***/ 

$actorSymbol (length)  =  1;//  null  terminator. 

/**/ 

/***StringLengthBlock ($channel) ***/ 

$actorSymbol (length)  +=  strlen ($ref (plus#$channel) ) ; 
/**/ 


/***StringAllocBlock***/ 

$actorSymbol (result)  =  (char*)  realloc ($ref (output) ,  $actorSymbol (length) ) ; 
strcpy ($actorSymbol (result) ,  $ref (plus#0) ) ; 

1**1 


/***StringAddBlock ($channel) ***/ 

strcat ($actorSymbol (result) ,  $ref (plus#$channel) ) ; 
/**/ 


/***TokenAddBlock ($channel) ***/ 

$actorSymbol (result)  =  $tokenFunc ($actorSymbol (result) : : add ($ref (plus#$channel) ) ) ; 
/**/ 


/***TokenMinusBlock ($channel) ***/ 

$actorSymbol (result)  =  $tokenFunc ($actorSymbol (result) : : substract ($ref (minus#$channel) ) ) ; 
1**1 

/***PostFireBlOCk***/ 

$ref (output)  =  $actorSymbol (result) ; 

/**/ 

C.3.2  How  to  write  the  helper  that  extends  another  concrete  helper 

The  following  is  the  Uniform  helper,  which  extends  the  RandomSource  helper: 

//  Uniform. java 
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public  class  Uniform  extends  RandomSource  { 

public  Uniform (ptolemy. actor. lib. Uniform  actor)  { 
super (actor) ; 

} 

protected  String  _generateRandomNumber ( )  throws  IllegalActionException  { 
return  _generateBlockCode ("randomBlock") ; 

} 


This  is  the  Uniform  helper’s  code  template  file  (Uniform. c): 

/***  randomBlock  ***/ 

$ref (output)  =  (RandomSource_nextDouble (&$actorSymbol (seed) ) 

*  ($val (upperBound)  -  $val (lowerBound) ) )  +  $val (lowerBound) ; 

/**/ 


It  references  the  function  RandomSourcenextDouble  from  its  parent’s  code  template.  The  follow¬ 
ing  is  the  code  template  for  the  RandomSource  helper  (RandomSource. c): 


/***  sharedBlock  ***/ 

int  RandomSource_next (int  bits,  double*  seed)  { 

*seed  =  (((long  long)  *seed  *  0x5DEECE66DLL)  +  OxBLL)  &  ((ILL  «  48)  -  lb- 
return  (int) ((signed  long  long)  *seed  »  (48  -  bits)); 


double  RandomSource_nextDouble (double*  seed)  { 

return  (((long  long) RandomSource_next (26,  seed)  «  27) 

+  RandomSource_next (27,  seed))  /  (double) (ILL  «  53); 


/**/ 


/***  gaussianBlock  ***/ 

double  RandomSource_nextGaussian (double*  seed,  boolean*  haveNextNextGaussian,  double*  nextNextGaussian)  { 
double  multiplier; 
double  vl; 
double  v2; 
double  s; 

if  (*haveNextNextGaussian)  { 

♦haveNextNextGaussian  =  false; 
return  *nextNextGaussian; 

}  else  { 
do  { 

vl  =  2  *  RandomSource_nextDouble (seed)  -  1;  //  between  -1.0  and  1.0 
v2  =  2  *  RandomSource_nextDouble (seed)  -  1;  //  between  -1.0  and  1.0 
s  =  vl  *  vl  +  v2  *  v2; 

}  while  (s  >=  1  ||  s  ==  0) ; 

multiplier  =  sqrt(-2  *  log ( s ) /s ) ; 

♦nextNextGaussian  =  v2  *  multiplier; 

♦haveNextNextGaussian  =  true; 
return  vl  *  multiplier; 

} 

} 

/**/ 

/***  setSeedBlockO ($hashCode)  ***/ 

$actorSymbol (seed)  =  $actorSymbol (seed)  =  time  (NULL)  +  $hashCode; 

/**/ 


/***  setSeedBlockl  ***/ 

/*  see  documentation  from  http: //java. sun ,com/j2se/l . 4 . 2/docs/api/java/util/Random.html#setSeed (long)  */ 
//this. seed  =  (seed  A  0x5DEECE66DL)  &  ( (1L  «  48)  -  1); 
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$actorSymbol (seed)  =  ((long  long)  $val(seed)  A  0x5DEECE66DLL)  &  ((ILL  «  48)  -  1); 
/**/ 

/***  preinitBlock  ***/ 
double  $actorSymbol (seed) ; 

/**/ 


Since  the  Uniform  helper  does  not  override  any  of  code  generation  methods,  the  parent’s  methods 
are  called  instead.  The  sharedBlock,  setSeedBlock  and  preinitBlock  code  blocks  are  harvested  from 
the  RandomSource  code  template.  The  child  helper  may  override  its  parent’s  code  blocks  while  using 
its  parent’s  code  generation  methods.  A  child  helper  can  also  override  the  code  generation  method. 
Neither  way  of  overriding  the  super  class’s  code  harvesting  increases  run-time  overhead  in  the  gener¬ 
ated  code.  The  code  generator  handles  method  /code  block  overrides  during  compile  time  and  add  no 
extra  logic  in  the  final  code. 
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Shuvra  S.  Bhattacharyya 

9.1  Introduction 

The  copemicus  package  is  an  infrastructure  for  building  code  generators  for  Ptolemy  II  models  by 
analyzing  the  Java  byte  code  by  using  the  Soot1  package.  The  primary  idea  behind  copemicus  was  to 
reuse  preexisting  actors  written  in  Java  thus  relieving  the  developer  from  the  task  of  rewriting  actors 
for  code  generation.  In  contrast  to  copemicus,  Ptolemy  II  also  includes  the  codegen  package,  docu¬ 
mented  in  chapter  8,  which  is  a  template  based  code  generation  system  that  requires  the  developer  to 
rewrite  actors.  For  further  information  about  the  various  Ptolemy  code  generators,  see  the  Ptolemy  II 
FAQ  at  http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIfaq.htm. 

The  basic  design  goal  of  the  copemicus  package  was  to  provide  a  common  interface  to  different 
Soot  based  code  generators  and  consolidate  some  of  the  basic  argument  handling  and  default  parame¬ 
ters.  Several  different  code  generators  of  varying  complexity  have  been  implemented.  There  is  also 
quite  a  bit  of  testing  infrastructure  for  integrating  code  generation  with  the  nightly  build  system. 

The  basic  infrastructure  is  implemented  in  the  copemicus.kemel  package.  The  Copemicus  class 
contains  a  main  function  suitable  for  invocation  from  the  command  line.  The  GeneratorAttribute  class 
represents  code  generation  parameters  that  can  be  persistently  added  to  a  model  for  unusual  configura¬ 
tions  of  a  code  generator.  The  KemelMain  class  is  a  base  class  from  which  classes  for  various  code 
generators  can  be  derived.  Instances  of  these  subclasses  are  instantiated  and  executed  in  a  code  gener¬ 
ation  job. 

The  Copemicus  class  itself  is  invoked  to  begin  code  generation  from  a  model.  If  invoked  from  the 
command  line,  it  reads  command  line  arguments  to  determine  various  code  generation  options  and  an 


1.  Soot  is  a  Java  Optimization  Framework  that  works  on  .class  files,  see  http://www.sable.mcgill.ca/soot/ 
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MoML  file  to  load  a  model  from.  If  invoked  via  various  static  methods,  code  generation  options  are 
assumed  to  be  passed  in  through  a  GeneratorAttribute.  Default  code  generation  options  are  specified  in 
the  Generator.xml  file.  One  of  the  code  generation  parameters  determines  the  code  generator  to  exe¬ 
cute.  The  class  representing  the  code  generator  is  loaded  through  reflection  and  invoked  through  the 
KemelMain  base  class. 

The  KemelMain  base  class  provides  default  behavior  for  most  code  generators.  It  performs  static 
analysis,  such  as  type  resolution  and  scheduling  by  invoking  the  Manager.preinitalizeAndResolve- 
Types()  method  and  then  passes  control  to  the  specific  code  generator. 

9.1.1  Default  options 

Most  code  generators  share  common  options.  The  following  options  are  defined  by  default  in  gen¬ 
erator.xml. 

codeGenerator:  The  code  generator  to  run. 

codeGeneratorClassName:  The  class  that  is  instantiated  to  execute  a  particular  code  generator. 
This  class  is  expected  to  be  a  subclass  of  ptolemy.copemicus.kemel.KemelMain. 

compile:  If  true,  compile  the  generated  code.  The  default  is  true. 

show:  If  true,  then  show  the  generated  code.  The  default  is  true. 

run:  If  true,  then  run  the  generated  code.  The  default  is  true. 

ptll:  The  location  of  the  Ptolemy  II  classes.  The  default  is  the  value  of  the  ptolemy.ptll.dir  Java 
system  property 

ptHUserDirectory:  The  top  level  directory  to  write  the  code  in.  The  default  is  the  value  of  the  ptll 
parameter.  The  code  will  appear  in  'ptllUserDirectory/targetpath'. 

targetPackage:  The  package  to  generate  code  in.  The  default  is  the  model  name 

targetPath:  The  path  relative  to  the  ptHUserDirectory  to  generate  code  in.  The  default  is  the  “eg” 
subdirectory  of  the  particular  code  generator. 

outputDirectory:  The  directory  that  code  will  be  generated  in.  By  default  this  is  the  targetPath 
parameter  appended  to  the  ptHUserDirectory  path. 

modelPath:  The  path  to  the  model,  including  the  .xml  extension.  The  modelPath  parameter  is  con¬ 
verted  to  a  URL  internally  before  use. 

compileOptions:  User  supplied  arguments  to  be  passed  to  the  code  generator.  Defaults  to  the 
empty  string. 
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javaClassPath:  The  Java  class  path,  converted  to  a  string. 

runCommandTemplateFile:  The  template  file  that  contains  the  command  to  run  the  generated 
code. 

runOptions:  User  supplied  arguments  to  be  passed  to  the  command  that  will  run  the  generated 
code.  Defaults  to  the  empty  string. 

sootDir:  The  directory  that  contains  the  soot  jar  files.  Defaults  to  the  value  of  the  ptll  parameter  + 
"/lib" 


sootClasses:  The  location  of  sootclasses.jar,  jasminclasses.jar  and  the  Java  system  jar  (usually 
rt.jar).  The  necessaryClassPath  parameter  may  end  up  duplicating  some  of  the  elements  of  this  param¬ 
eter. 


watchDogTimeout:  The  number  of  milliseconds  that  code  generation  will  run  for.  Defaults  to 
720000,  which  is  12  minutes.  The  watchdog  is  used  to  prevent  the  code  generator  and  the  generated 
code  from  hanging  the  nightly  build. 

output:  The  filename  to  redirect  the  standard  output  stream  of  the  code  generator  to.  This  is  used, 
for  example,  in  the  nightly  build  to  provide  easily  parseable  error  messages.  If  the  value  is  not  set, 
then  the  output  will  not  be  redirected. 


9.2  Copernicus  Java  Code  Generator 

The  Copernicus  Java  code  generator  is  implemented  by  the  Copernicus. java  package.  This  code 
generator  targets  the  generation  of  self-contained  Java  code  optimized  for  code  size,  memory  usage 
and  execution  speed.  The  Java  code  generator  leverages  the  Soot  compiler  framework  to  parse  the 
bytecode  for  each  atomic  actor  in  the  model.  The  actors  are  then  specialized  according  to  their  context 
in  the  model. 

The  Copernicus  Java  code  generator  operates  in  several  phases,  and  the  output  of  each  phase  is  a 
partially  specialized  model.  The  output  from  the  intermediate  phases  can  be  generated  by  setting  the 
snapshots  parameter  to  be  true.  The  first  snapshot  consists  of  self-contained  code  specialized  to  the 
domains  in  the  model.  The  second  snapshot  is  additionally  specialized  to  the  parameter  values  in  the 
model,  while  the  third  is  specialized  to  the  structure  of  the  model.  The  fourth  snapshot  eliminates  all 
references  to  Ptolemy  named  objects  in  the  model,  resulting  in  self-contained  code  without  component 
interfaces.  The  final  generated  code  has  also  been  specialized  for  data  types  and  contains  no  references 
to  Ptolemy  tokens. 

One  of  the  goals  of  the  Copernicus  Java  code  generator  was  to  avoid  separate  specifications  for 
simulation  and  code  generation  wherever  possible.  The  Copernicus  Java  code  generator  operates  by 
transforming  Java  actor  specifications  (actor  classes)  and  on  Java  data  type  specifications  (token 
classes).  In  most  cases,  new  actor  and  token  classes  will  be  leveraged  transparently  by  the  code  gener- 
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ator.  Unfortunately,  domain  specifications  are  not  as  easily  reused  and  the  Copernicus  Java  code  gener¬ 
ator  contains  “re-implementations”  of  domains  for  code  generation.  This  allows  for  more  efficient 
code  to  be  generated,  at  the  expense  of  duplicating  aspects  of  existing  Director  and  Receiver  code,  and 
making  it  more  difficult  for  new  domains  to  be  implemented  in  code  generation. 

In  order  for  existing  actor  code  to  be  leveraged  by  the  code  generator,  it  assumes  that  the  code  is 
written  according  to  the  Ptolemy  style  for  writing  actors.  This  style  assumes  naming  conventions  for 
the  public  fields  of  an  actor  class  that  refer  to  parameters  and  ports  of  the  actor.  The  code  generator 
also  assumes  that  the  ports  and  parameters  of  an  actor  are  created  in  the  class  constructor  and  not  mod¬ 
ified  later.  Some  actors  do  not  fit  these  constraints  and  cannot  be  used  directly  in  the  code  generator. 
Such  actor  classes  cannot  be  used  directly  by  the  code  generator,  although  in  some  cases  we  have  been 
able  to  have  the  code  generator  deal  specially  with  such  actors.  In  other  cases,  the  actor  class  fits  the 
constraints  but  cannot  be  effectively  specialized  using  generic  techniques.  Such  actors  can  also  be 
dealt  with  specially  by  the  code  generator  to  more  effectively  generate  code. 

9.2.1  Software  Architecture 

The  Copernicus  Java  code  generator  consists  of  a  large  number  of  individual  transformation  steps, 
which  will  not  be  described  here.  These  transformation  steps  are  implemented  by  classes  extending  the 
SceneTransformer  class,  or  the  Body  Transformer  class.  Two  key  points  of  extensibility  are  provided 
for  generating  domain  code  and  for  generating  actor  code  to  replace  unspecializable  actor  classes. 

Code  generation  for  specific  domains  is  handled  by  various  implementations  of  the  DomainCode- 
Generator  interface.  An  implementation  of  this  interface  is  responsible  for  generating  domain  interac¬ 
tion  code  for  a  particular  composite  actor  in  the  hierarchy,  including  code  to  invoke  the  methods  of 
various  actors  and  domain-specific  communication  structures.  Currently,  the  following  domains  are 
handled: 

Synchronous  Dataflow  (SDF):  The  SDF  implementation  transforms  the  SDF  schedule  into  Java 
code  that  invokes  the  actors  in  a  model.  Fixed  size  arrays  are  generated  for  communication  buffers 
dedicated  to  each  relation  in  the  model,  and  communication  methods  are  replaced  with  circularly 
indexed  addressing  into  the  communication  buffers. 

Hybrid  Systems  (HS):  The  hybrid  systems  director  deals  with  modal  models.  Currently,  only  the 
subset  that  is  useful  in  modal  SDF  models  is  implemented. 

Giotto:  The  Giotto  implementation  interfaces  directly  with  the  Java  output  of  the  Giotto  compiler. 
It  generates  classes  with  static  methods  used  for  communication  by  the  Giotto  compiler  and  generates 
a  .giotto  file  that  describes  the  classes  implementing  the  various  Giotto  tasks.  The  Giotto  compiler 
compiles  this  file  into  a  class  that  implements  the  Giotto  task  scheduling  model. 

Code  Generation  for  actors  is  handled  various  implementations  of  the  AtomicActorCreator  inter¬ 
face.  An  implementation  of  this  interface  generates  a  self-contained  class  for  a  particular  actor.  The 
default  implementation  of  this  interface,  the  GenericAtomicActorCreator  class,  simply  copies  the 
existing  actor  specification  code.  Other  implementations  of  the  interface  deal  with  generating  code  for 
specific  actors.  Currently  the  following  actors  are  handled  specially: 

Expression:  The  standard  implementation  of  this  actor  builds  a  parse  tree  for  the  expression  and 
traverses  the  parse  tree  to  evaluate  it  at  run  time.  This  actor  is  handled  specifically  by  the  Expression- 
Creator  class  for  two  reasons.  Primarily,  the  parse  tree  is  convenient  way  of  representing  an  arbitrary 
expression,  but  much  simpler  code  can  be  generated  for  a  specific  expression.  Secondarily,  the  parse 
tree  complicates  other  transformations  that  specialize  communication  between  actors  and  data  types. 

FSMActor:  The  standard  implementation  of  this  actor  builds  parse  trees  for  every  expression  in  a 
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model,  and  suffers  from  the  same  drawbacks  as  the  Expression  actor.  The  FSMActor  also  attempts  to 
deal  with  run-time  modifications  of  the  finite-state  machine  in  an  efficient  manner,  which  is  not  neces¬ 
sary  in  generated  code.  This  actor  is  handled  specifically  by  the  FSMCreator  class. 

Many  actors  are  not  handled  specifically,  but  should  be.  Flere  is  a  short  list: 

MathFunction:  This  actor  creates  and  deletes  its  ports  based  on  a  parameter  value.  In  generated 
code  will  likely  not  happen  (since  the  parameter  value  is  not  likely  to  change),  but  the  GenericAtomi- 
cActorCreator  is  not  smart  enough  to  deal  with  ports  that  are  not  created  in  the  constructor.  It  is  likely 
easiest  to  handle  this  actor  by  handling  it  specially  and  checking  that  the  parameter  value  does  not 
change  using  reconfiguration  analysis. 

TypeTest:  This  actor  tests  the  type  system,  but  has  no  run-time  behavior.  It  is  problematic  because 
it  iterates  over  all  of  the  actors  in  a  model,  which  is  currently  not  supported  by  the  code  generation 
mechanism.  It  could  probably  be  checked  statically  and  ignored  in  generated  code. 

RecordAssembler  and  RecordDisassembler:  These  actors  iterator  over  their  input  and  output  ports 
to  construct  a  record.  They  could  either  be  dealt  with  specially,  or  the  code  generator  could  be 
improved  to  unroll  iterators  over  ports. 

ExpressionToToken  and  ExpressionReader:  These  actors  operate  in  a  similar  way  to  the  expres¬ 
sion  actor,  except  that  the  expression  is  received  from  an  input  port.  Because  of  this,  code  generation 
will  not  work.  It  is  not  clear  how  to  make  this  actor  work  nicely  with  type  specialization. 

9.2.2  Generated  Code 

The  code  generated  from  the  Copernicus  Java  code  generator  is  a  set  of  self-contained  Java  .class 
files  with  a  command-line  interface.  A  makefile  is  automatically  generated  with  a  large  number  of 
rules  for  manipulating  the  generated  code.  The  makefile  rules  are: 

runJava:  Run  the  generated  code. 

compareAll:  Run  a  series  of  comparisons  between  the  simulation  model,  the  generated  code,  and 
the  obfuscated  version  of  the  generated  code  comparing  code  size,  execution  speed,  and  memory 
usage. 

treeShake:  Generate  a  self-contained  .jar  file  containing  only  code  necessary  for  the  generated 
code.  This  rule  uses  reachable  method  information  gained  through  static  analysis  in  the  code  generator, 
if  possible. 

treeShakeByRunning:  Generate  a  self-contained  .jar  file  containing  only  code  necessary  for  the 
generated  code.  This  rule  executes  the  generated  code  and  extracts  information  from  the  virtual 
machine  about  which  classes  were  loaded  at  runtime. 

runTreeShake:  Run  the  generated  code  from  the  self-contained  .jar  file. 

profileTreeShake:  Run  the  generated  code  from  the  self-contained  .jar  file  with  profiling  options  to 
report  runtime  memory  usage.  An  average  of  several  runs  is  reported. 

treeShake WithoutCodegen:  Generate  a  self-contained  .jar  file  containing  only  code  necessary  for 
executing  the  simulation  model.  This  rule  executes  the  generated  code  and  extracts  information  from 
the  virtual  machine  about  which  classes  were  loaded  at  runtime. 

runTreeShakeWithoutCodegen:  Run  the  original  simulation  model  from  the  self-contained  .jar 

file. 

profileTreeShake  WithoutCodegen:  Run  the  original  simulation  model  from  the  self-contained  .jar 
file  with  profiling  options  to  report  runtime  memory  usage.  An  average  of  several  runs  is  reported. 

obfuscate:  Run  the  Jode  obfuscator  on  the  generated  code,  to  minimize  the  size  of  the  generated 
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.jar  file. 

runObfuscate:  Run  the  obfuscated  version  of  the  generated  code. 

profileObfuscate:  Run  the  obfuscated  version  of  the  generated  code  from  the  self-contained  .jar 
file  with  profiling  options  to  report  runtime  memory  usage.  An  average  of  several  runs  is  reported. 

gcj:  Compile  the  generated  code  into  a  native  executable  using  gcj.  Note:  this  will  likely  only  work 
for  simple  models,  as  the  gcj  standard  Java  libraries  are  far  from  complete. 

9.2.3  Java  Code  Generation  Demonstrations 

Below  are  several  demonstrations  of  the  Copernicus  Java  code  generator.  Our  canonical  Java  code 
generation  model  is  the  OrthogonalCom  model  located  in  $PTII/ptolemy/domains/sdf/demo/Orthogo- 
nalCom/OrthogonalCom.xm,  see  Figure  9.11. 
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This  model  is  used  as  a  test  case  for 
code  generation.  It  produces  data 
on  standard  out,  so  nothing  much  happens 
when  it  is  run  In  the  standard  interpreted 
mode. 

To  run  the  code  generator, 
select  View  ->  Code  Generator. 

See  SPTIl/doc/codegen.htm  for  details. 
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FIGURE  9.1.  The  Orthogonal  Communication  model,  used  as  a  Java  code  generation 
example. 


We  use  the  copemicus  shell  script,  located  at  $PTII/bin/copemicus  to  run  the  Copernicus  Java  code 
generator: 

$PTI I /bin/copernicus  -codeGenerator  java  $PTII/ptolemy /domains/ sdf /demo/OrthogonalCom/OrthogonalCom. xml 


The  above  command  will  generate  voluminous  output  and  eventually  create  .class  files  in  $PTII/ 
ptolemy/copemicus/java/cg/OrthogonalCom  and  run  the  generated  code. 

Treeshaking. 
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The  copernicus  script  also  generates  a  makefile  in  the  output  directory  that  contain  rules  to  per¬ 
form  operations  like  treeshaking  and  obfuscation.  Treeshaking  is  an  optimization  where  we  run  the 
model,  note  what  .class  files  are  loaded  and  then  place  those  .class  files  in  ajar  file.  Treeshaking  is  not 
perfect,  since  if  the  model  is  running  from  the  jar  file  and  later  throws  an  exception  the  error  handlers 
and  other  .class  files  might  not  be  present.  Obfuscation  is  an  optimization  that  shortens  class  and 
method  names  so  as  to  decrease  the  size  of  the  jar  file. 

We  use  Jode  to  obfuscate  the  code.  Jode  is  available  from  http://jode.sourceforge.net/.  Unfortu¬ 
nately,  Jode  is  distributed  under  the  GNU  General  Public  License  (GPL),  so  we  do  not  include  it  in  the 
Ptolemy  release.  In  addition  Jode  might  not  work  with  Java  1.5.  To  set  up  Jode: 

1.  Download  Jode  so  that  $PTII/vendors/jode/l.l.l/jode.jar  is  present. 

2.  Re  run  configure  with: 

cd  $  PTI I 
. / configure 

Then  go  back  to  the  output  directory  and  run  make: 

$PTI I / ptolemy/ copernicus/ j  ava/ eg/ OrthogonalCom 
make  compareAll 

Setting  the  iterations. 

The  truly  observant  will  have  noticed  that  the  various  versions  of  the  model  ran  very  quickly  and 
that  it  is  difficult  to  compare  the  time  performance  of  the  different  versions.  The  solution  is  to  increase 
the  number  of  iterations  so  that  we  can  see  differences  in  time  performance.  $PTII/ptolemy/copemi- 
cus/kemel/KemelMain.java  describes  how  to  set  the  iterations: 

*  If  the  director  is  an  SDF  director,  then  the  number  of 

*  iterations  is  handled  specially.  If  the  director  is  an  SDF 

*  director  and  a  parameter  called  "copernicus  iterations"  is 

*  present,  then  the  value  of  that  parameter  is  used  as  the 

*  number  of  iterations.  If  the  director  is  an  SDF  director,  and 

*  there  is  no  "copernicus  iterations"  parameter  but  the 

*  "ptolemy .ptll . copernicuslterations"  Java  property  is  set,  then 

*  the  value  of  that  property  is  used  as  the  number  of 

*  iterations. 

So,  we  can  either  edit  the  model  and  add  a  copernicus  lterations  parameter,  or  else  we  can  run 
copernicus  with  the  ptolemy.ptll.copemicuslterations  property  set.  In  this  example,  we  set  the  property 
and  rerun  copernicus 


export  USERJAVAPROPERTIES=-Dptolemy .ptll . copernicus I terations=l 00 

$PTII/bin/copernicus  -codeGenerator  java  $PTII/ptolemy/domains/ sdf /demo/OrthogonalCom/OrthogonalCom. xml 


Then,  we  cd  to  the  generated  directory  and  re  run  the  comparison: 

cd  $PTI I / ptolemy/ copernicus/ j  ava/ eg/ OrthogonalCom 
make  compareAll 

The  results  is  that  the  different  versions  of  the  models  run  for  1 000  iterations  and  we  can  compare 
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the  times: 


Table  15:  Jar  file  sizes  and  elapsed  time 


Optimizations 

Jar  file  size 

Time 

interpreted  code  with  treeshaking 

-750  k  bytes 

4787  ms. 

copernicus  generated  code  with  treeshaking 

-77  k  bytes 

230  ms. 

copernicus  generated  code  with  treeshaking 
and  obfuscation 

-40  k  bytes 

217  ms. 

Note  that  these  results  are  not  particularly  rigorous,  see  [119]  for  a  more  formal  analysis. 


9.3  Copernicus  C  Code  Generator 

The  Copernicus  C  code  generator  [147]  is  implemented  by  the  copernicus. c  package.  This  code 
generator  targets  the  generation  of  self-contained  C  code  by  post-processing  the  result  of  the  Coperni¬ 
cus  Java  code  generator,  and  performing  further  code  size  optimizations.  The  Copernicus  C  code  gen¬ 
erator  leverages  the  Soot  compiler  framework  to  parse  the  bytecode  representation  for  each  class  to  be 
compiled.  Note  that  work  on  the  Copernicus  C  code  generator  has  stopped,  the  Ptolemy  group  is  work¬ 
ing  on  a  template  based  code  generator. 

Within  the  Ptolemy  II  framework,  the  C  code  generator  takes  the  class  files  generated  by  coperni- 
cus.java  as  input. The  C  code  generator  can  also  be  used  as  a  stand-alone  Java-to-C  compiler  to  gener¬ 
ate  C  code  for  arbitrary  Java  programs. 

9.3.1  Code  Generation 

The  main  steps  in  the  code  generation  algorithm  are  as  follows: 

1.  Read  in  main  class  file  using  Soot. 

2.  Use  CallGraphPruner  to  compute  the  set  of  required  methods,  classes  and  fields. 

3.  Generate  .c  and  .h  files  for  the  main  class(es). 

4.  Generate  a  .c  file  containing  code  for  initialization  and  setup. 

5.  Generate  .c  and  .h  files  for  all  required  Java  library  classes  in  a  separate  directory  (named  j2c_lib 
by  default).  Note  that  these  only  contain  code  for  required  methods  and  fields,  to  minimize  code 
size.  The  code  for  each  method  is  generated  by  converting  the  jimple  statements  for  the  method’s 
body  atomically  into  the  appropriate  C  constructs. 

6.  Generate  a  makefile  for  compiling  the  code  into  an  executable. 

9.3.2  The  Code  Pruning  Algorithm 

The  Soot  framework  is  used  to  create  a  Call  Graph  of  the  application.  This  is  a  graph  with  methods 
as  the  nodes,  and  calls  from  one  method  to  another  as  directed  edges. 
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At  first  glance,  it  seems  that  the  transitive  closure  of  the  methods  in  the  main  class  should  repre¬ 
sent  all  methods  that  can  be  called.  However,  this  is  not  so,  because  the  first  time  the  field  or  method  of 
a  class  is  referenced,  its  class  initialization  method  is  also  invoked,  and  this  can  reference  other  meth¬ 
ods  or  fields  in  turn. 

The  method  call  graph  also  contains  an  edge  from  a  method  to  every  possible  target  of  method 
calls  in  it.  The  number  of  such  targets  can  be  large  for  polymorphic  method  calls.  A  more  sophisticated 
analysis  can  trim  the  method  call  graph  by  removing  some  of  the  edges  corresponding  to  polymorphic 
invocations. 

We  use  Soot’s  Variable  Type  Analysis  (VTA)  to  perform  this  call  graph  trimming.  This  analysis 
computes  the  possible  runtime  types  of  each  variable  using  a  reaching  type  analysis,  and  uses  this 
information  to  remove  spurious  edges. 

Computing  the  Set  of  Required  Entities. 

From  the  analysis  mentioned  above,  the  set  of  all  possible  required  classes,  methods  and  fields 
(collectively  grouped  as  entities)  can  be  statically  computed.  We  use  a  set  of  rules  to  determine  which 
classes  are  required. 

1.  A  set  of  compulsory  entities  is  always  required.  This  includes  the  System.  initializeSys- 
temClass  ( )  method,  all  methods  and  fields  of  the  j  ava .  lang .  Ob  j  ect  class  (since  it  is  the 
global  superclass)  and  the  main  method  of  the  main  class  to  be  compiled. 

2.  If  a  method  m  is  required,  the  following  also  become  required:  the  class  declaring  m,  all  methods 
that  may  possibly  be  called  by  m,  all  fields  accessed  in  the  body  of  m ,  the  classes  of  all  local  vari¬ 
ables  and  arguments  of  m,  the  classes  corresponding  to  all  exceptions  that  may  be  caught  or 
thrown  by  m,  and  the  method  corresponding  to  m  in  all  required  subclasses  of  the  class  declaring 
m. 

3.  If  a  field /is  required,  the  following  also  become  required:  the  class  declaring/  the  class  corre¬ 
sponding  to  the  type  of /  (if  any)  and  the  field  corresponding  to  /  in  all  required  subclasses  of  the 
class  declaring  it. 

4.  If  a  class  c  is  required,  the  following  also  become  required:  all  superclasses  of  c,  the  class  initial¬ 
ization  method  of  c,  and  the  instance  initialization  method  of  c. 

Interfaces  are  treated  as  classes.  A  worklist-based  algorithm  can  be  used  to  add  to  the  set  of 
required  entities  until  no  additional  entities  can  be  found  by  application  of  these  rules.  Together,  rules 
2,  3  and  4  encapsulate  all  possible  dependencies  between  entities.  This  makes  the  set  of  required  enti¬ 
ties  self-contained. 

9.3.3  Limitations 

The  restrictions  imposed  C-based  static  compilation  strategy  are: 

•  Dynamic  Loading  and  Reflection  are  not  supported. 

•  The  generated  executable  runs  as  a  user  process,  so  applications  that  rely  on  a  JVM  as  a  buffer 
between  them  and  the  platform  for  security  cannot  be  guaranteed  to  run  correctly. 

The  further  limitations  of  the  current  implementation  are: 

•  No  support  for  threads. 

•  GUI-based  functions  are  currently  not  implemented. 

•  Certain  java  classes  are  not  currently  supported,  because  the  native  methods  for  them  need  to  be 
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coded.  The  list  of  these  is  maintained  in  the  OverriddenMethodGenerator  class. 

9.3.4  Options 

There  are  a  number  of  command-line  options  available: 

•  verbose:  true/false  Turns  verbose  mode  on  or  off. 

•  compileMode:  singleClass  compiles  only  the  given  class ,/«//  generates  all  required  files. 

•  pruneLevel:  0  no  code  pruning  done,  1  code  pruning  done  by  CallGraphPruner. 

•  vta:  true/false  Whether  or  not  to  perform  Variable  Type  Analysis. 

•  lib:  the  path  to  the  directory  where  library  of  generated  files  should  be  stored. 

•  gcDir:  stores  the  path  to  the  directory  containing  the  garbage  collector.  Not  using  this  option  turns 
the  collector  off. 

•  target:  The  target  platform.  A  blank  refers  to  a  generic  POSIX-like  system  including  Cygwin 
installations.  C6000  The  TMS320C6xxx  series  of  processors. 

•  runtimeDir:  The  path  to  the  runtime  directory. 

•  ptll:  The  path  to  the  ptll  directory. 

•  compulsoryMethods:  A  semicolon-separated  list  of  methods  for  which  code  must  always  be  gener¬ 
ated.  If  more  than  one  such  entity  is  to  be  specified,  the  entire  list  may  be  enclosed  within  double 
quotes.  The  complete  method  subsignature  of  the  form  returnType  class. method(argl ,  arg2,  ...) 
must  be  specified. 

•  cFlags:  The  GCC  flags  to  be  used  in  the  makefile. 

•  reportEntities:  true/false  whether  to  output  a  summary  of  the  number  of  classes,  methods  and 
fields  (entities)  generated. 

9.3.5  Directory  structure 

The  main  subdirectories  in  copemicus.c  are: 

•  runtime:  Contains  a  small  amount  of  C  code  that  provides  basic  functionality.  This  is  linked  in 
while  generating  the  executables. 

•  runtime/native  bodies:  C  code  for  native  methods. 

•  runtime/over  bodies:  C  code  for  methods  with  custom  code. 

•  test:  Various  test  programs. 

•  testOutput:  Auto-generated  C  code. 

9.3.6  Code  Flow 

The  following  UML  diagram  shows  the  various  classes  that  populate  copemicus.c.  This  is  a  rela¬ 
tively  complex  package,  so  many  implementation  details  have  been  abstracted  out.  Complete  descrip¬ 
tions  of  all  classes  and  their  members  are  available  in  the  API,  and  we  attempt  to  provide  an  insight 
into  the  higher-level  structure  of  the  package  here. 

•  Protected  and  private  methods  are  not  shown,  unless  they  are  central  to  the  functionality  of  the 
class. 

•  Unimportant  external  superclasses  are  not  shown  here. 

•  Public  methods  that  are  not  central  to  the  operation  of  the  class  are  omitted. 

•  CSwitch  has  a  caseXXX  method  for  each  kind  of  Jimple  statement  XXX.  These  are  shown  as  a 
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single  entry  in  the  figure. 

•  The  methods  in  ExceptionTracker  are  omitted.  This  class  tracks  the  current  exceptions  and  works 

closely  with  MethodCodeGenerator.  However,  the  C  implementation  of  Java  exceptions  is  com¬ 
plex  and  is  not  discussed  here. 

The  dashed  arrows  in  the  UML  diagram  represent  the  coarse-grained  code  flow  in  copemicus.c. 
The  entry  class  is  JavaToC  when  used  in  stand-alone  mode,  and  Main  when  copemicus.c  is  used  as  a 
ptolemy  code-generation  back-end. 

JavaToC  reads  in  a  Java  class  file  and  implicitly  converts  it  to  the  Soot  Jimple  format.  Then  it  calls 
RequiredFileGenerator,  MakeFileGenerator  and  MainFileGenerator. 

RequiredFileGenerator  uses  CallGraphPruner  to  compute  the  set  of  required  classes,  methods  and 
fields.  Then  it  calls  ClassFileGenerator,  HeaderFileGenerator  and  StubFileGenerator  on  each  required 
class. 

ClassFileGenerator  creates  the  .c  file  containing  all  the  function  definitions.  Each  of  these  function 
definitions  is  created  by  MethodCodeGenerator.  MethodCodeGenerator  calls  CSwitch  on  each  Jimple 
statement  to  find  its  C  equivalent. 

HeaderFileGenerator  creates  the  .h  file  corresponding  to  the  class.  This  consists  of  a  class-specific 
C  structure  for  the  class  (created  by  ClassStructureGenerator),  an  instance-specific  C  structure  for  the 
class  (created  by  InstanceStructureGenerator)  and  various  function  declarations.  MethodFistGenerator 
is  the  class  that  “understands”  inheritance  to  create  the  lists  of  constructors,  inherited  methods,  new 
methods,  private  methods,  etc. 

StubFileGenerator  creates  a  small  “stub”  of  prototype  declarations  useful  for  breaking  circular 
dependencies  between  classes. 

MakeFileGenerator  creates  a  makefile  proving  rules  for  compiling  the  generated  C  code  into  an 
executable. 

MainFileGenerator  creates  a  file  that  contains  the  C  “main”  method,  which  performs  initialization 
functions,  wraps  the  command-line  arguments  into  the  C  equivalent  of  a  Java  string  array  and  passes 
them  to  the  “java”  main  method. 

In  addition,  CNames  converts  Java  names  into  unique  legal  C  names,  InterfaceFookupGenerator 
takes  care  of  resolving  interface  method  invocations,  FileHandler  provides  file  I/O  utilities,  Options 
stores  configuration  information,  Context  handles  useful  global  information,  NativeMethodGenerator 
handles  native  methods  and  OverriddenMethodGenerator  allows  user-defined  code  to  override  the 
compiler. 


9.3.7  HOWTOs 

Generating  an  executable  from  a  Java  ClassFile. 

Put  the  classfile  in  c/test 

cd  test 

java  -classpath  $classpath  ptolemy . copernicus . c . JavaToC  $classpath  className 

(note  that  the  classpath  has  to  be  specified  twice) 

make  -s  -f  classname . make 

Generating  Code  from  a  MoML  model. 
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ptolemy.copernicus.java.Main 


+convert(classPath  :  String,  className  :  String)| 
+main(args :  String[]) 


+completedTransform() :  boolean 
+internalTransform(phaseName  :  String,  options  :  Map)! 


CodeGenerator 


+generate(source  :  SootClass) :  String  I 


CodeFileGenerator 


soot.SceneTransformer 


MakeFileGenerator 


+generateMakeFile(classPath  :  String,  className  :  String) 


MainFileGenerator 


HeaderFileGenerator 


StubFileGenerator 


RequiredFileGenerator 


+qenerateUserClasses(code  :  StrinqBuffer) :  HashSet 
+qenerateTransitiveClosureOf(classPath  :  String,  className  :  String)! 


+qetRequiredClassesO :  Collection 
+isRequired(source  :  SootClass) :  boolean 
+isRequired(method  :  SootMethod) :  boolean 
+isRequired(field  :  SootField) :  boolean 
+isRequired(type  :  Type) :  boolean 


+getReachableClasses() :  HashSet 
+getReachableMethods() :  HashSet 
+getReachableFields() :  HashSet 
+CallGraphPruner(source :  SootClass)! 


NativeMethodGenerator 


+qenerateStub(method  :  SootMethod) 
+qetCode(method  :  SootMethod) :  String 


MethodCodeGenerator 


+generate(method  :  SootMethod) 


ExceptionTracker 


ClassStructureGenerator 

InstanceStructureGenerator 

MethodListGenerator 


+qetClasslnitializer(source  :  SootClass) :  SootMethod 
|+qetConstructors(source  :  SootClass) :  LinkedList 
+qetlnheritedMethods(source  :  SootClass) :  LinkedList| 
+qetNewMethods(source  :  SootClass) :  LinkedList 
|+qetPrivateMethods(source  :  SootClass) :  LinkedList 


+case...() 

|#_pop() :  String 
#_push(codeString :  String)! 


InterfaceLookupGenerator 


+qenerate(source  :  SootClass) :  String 
+needsl_ookupMethods(source  :  SootClass) :  boolean| 
+getLookupMethods() :  HashMap 


+classNameOf(source  :  SootClass) :  String 
+field  NameOff  field  :  SootField) :  String 
+functionNameOf(method  :  SootMethod) :  String 


+instanceNameOf(source  :  SootClass) :  String 
|+localNameOf(local :  soot.Local) :  String 
+typeNameOf(type  :  Type) :  String 


+addArraylnstances(instances :  Collection)! 
+addlncludeFile(fileName :  String) 

+clear() 

+getlncludeFiles() :  Iterator 
+getArraylnstances() :  HashSet 
+newStringConstant(value  :  String) :  String 
+getStringConstants() :  Iterator 


OverriddenMethodGenerator 


+getCode(method  :  SootMethod) :  String 
+isOverridden(method  :  SootMethod) :  boolean| 
+isOverridden(source  :  SootClass) :  boolean 


AnalysisUtilities 


+classesRequiredBy(field  :  SootField) :  LinkedList 
+qetAlllnterfacesOf(source  :  SootClass) :  HashSet 
+qetArqumentClasses(method  :  SootMethod) :  HashSet 
+qetl_ocalTypeClasses(method  :  SootMethod) :  HashSet| 
+qetSuperlnterfacesOf(source  :  SootClass) :  HashSet 


InstanceOfFunctionGenerator 


+generate(source  :  SootClass) :  String 


+comment(text :  String) :  Stringj 
+indent(level :  int) :  String 


FileHandler 

Options 

+exists(fileName  :  String) :  boolean 

+get(key :  String) :  String 
+put(key  :  String,  value  :  String) 
+v() :  Options 

+readStrinqFromFile(fileName  :  String) :  String 

+write(fileName  :  String,  code  :  String) 
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Move  the  xml  model  to  c/test/simple 

java  ptolemy . copernicus . kernel . Copernicus  -codeGenerator  c  model. xml 
Writing  Code  for  a  Native  Method. 

Java  requires  certain  native  methods,  which  are  methods  implemented  in  platform-dependent 
code,  typically  written  in  another  programming  language  such  as  C.  The  C  code  generator  allows  the 
user  to  specify  C  code  for  the  body  of  any  native  method.  At  compile-time,  this  is  integrated  with  the 
generated  C  code,  allowing  any  C  native  methods  to  be  fully  supported.  To  do  this: 

1 .  Find  the  C  name  of  that  method  (say  f00xx_abc). 

2.  Create  a  fde  by  this  name  (f00xx_abc.c )  in  runtime/native  bodies,  containing  the  code  for  that 
method. 

3.  Add  this  method  to  the  list  of  native  methods  in  NativeMethodGenerator. 

Overriding  Code  for  an  Existing  Method. 

It  is  also  possible  to  override  the  C  code  generator  and  write  custom  C  code  for  a  given  method 
instead.  To  do  this: 

1.  Find  the  C  name  of  that  method  (say  f00xx_abc). 

2.  Create  a  file  by  this  name  (f00xx_abc.c )  in  runtime/over  bodies,  containing  the  code  for  that 
method. 

3.  Add  this  method  to  the  list  of  overridden  methods  in  OverriddenMethodGenerator. 

Note  that  the  term  overridden  in  this  context  does  not  refer  to  methods  that  are  overridden  through 
inheritance  in  Java  classes. 

Suppressing  Code  Generation  for  a  Method,  Class  or  Package. 

To  “turn  off’  code  generation  for  a  method,  override  it  without  creating  code  for  it  in  runtime/ 
over  bodies.  For  an  entire  class  or  package,  list  it  in  OverriddenMethodGenerator.isOverridden- 
Class().  This  will  generate  methods  with  blank  bodies  and  trivial  return  statements  which  will  return  0 
or  NULL. 

CAVEAT:  Make  sure  that  the  returned  values  are  not  used.  Referencing  a  NULL  pointer  will  cause 
the  executable  to  throw  a  segmentation  fault. 

9.4  Applet  Code  Generator 

The  Applet  code  generator  takes  a  model  and  creates  HTML  files  for  use  as  a  web  based  applet. 
The  applet  generator  reads  template  files  that  end  in  .in  from  $PTII/ptolemy/copemicus/applet 
substitutes  keywords  and  writes  out  the  files  in  the  destination  directory.  Users  may  modify  the  tem¬ 
plate  files  to  match  their  local  setup 

Making  an  applet  available  via  the  web  is  somewhat  complex  because  the  Java  Plugin  has  two  sec¬ 
tions,  one  for  Netscape,  the  other  for  Internet  Explorer,  so  changes  to  the  htm  files  must  be  replicated 
in  both  sections.  The  codebase  and  the  location  of  the  jar  files  also  add  to  the  problems. 

If  a  model  is  named  MyModel,  and  the  user  selects  foo.bar  as  the  package,  then  saving  the  model 
as  an  applet  will  create  a  directory  called  $PTII/foo/bar/MyModel  and  create  the  following  files  for 
that  model: 
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makefile 

make  demo  will  run  appletviewer  on  the  HTML  files 

MyModel.xml 

A  local  copy  of  the  model 

MyModel.htm 

An  HTML  file  containing  the  code  necessary  to  MyModel.xml 
MyModelVergil.htm 

An  HTML  file  containing  the  code  necessary  to  display  MyModel.xml  graphically,  using 
ptolemy.vergil.VergilApplet  and  in  text  format 

9.4.1  Applet  Code  Generation  demonstrations 

Below  are  several  demonstrations  of  the  applet  code  generator.  The  code  generator  graphical  user 
interface  is  difficult  to  use,  so  we  recommend  using  the  copemicus  command  instead  of  using  the  code 
generator  GUI. 

The  OrthogonalCom  model  generates  prints  output  to  standard  out,  so  when  this  model  is  run  as  an 
applet,  the  output  will  appear  in  the  Java  Plugin  console.  Instead,  we  generate  an  applet  for  the  Butter¬ 
fly  model,  which  will  generate  display  a  nice  plot.  Note  that  the  Butterfly  model  uses  the  Expression 
actor  so  that  while  we  cannot  use  deep  code  generation  on  the  Butterfly  actor,  we  can  generate  an 
applet  for  this  model. 

Copernicus  command  -  create  applet  within  the  Ptolemy  tree. 

To  create  the  html  file  and  open  it  with  the  browser: 

cd  $PTII/ptolemy/domains/ sdf /demo/Butterf ly 

$PTI I /bin/copernicus  -codeGenerator  applet  Butterfly . xml 

The  HTML  can  be  found  in  $PTII/ptolemy/copemicus/applet/cg/Butterfly. 

Applet  code  generator  GUI  -  create  applet  within  the  Ptolemy  Tree. 

If  you  would  like  to  generate  an  applet  in  a  directory  within  the  Ptolemy  tree  using  the  experimen¬ 
tal  code  generation  GUI,  follow  these  steps: 

1.  Open  up  the  SDF  Butterfly  Model  at  $PTII/ptolemy/domains/sdf/demo/Butterfly/Butterfly.xml. 

2.  In  the  left  hand  actor  tree,  select  More  Libraries  ->  Codegen  ->  Copemicus  and  drag  a  SDF  Code- 
generator  into  the  main  window. 

3.  Double  click  on  the  SDF  Codegenerator. 

4.  Change  the  CodeGenerator  combo  box  from  java  to  applet 

5.  Hit  the  Generate  Button 

6.  The  code  generator  will  invoke  an  separate  java  process  that  generates  code  in  $PTII/ptolemy/ 
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copemicus/applet/cg/Butterfly  and  then  opens  the  generated  file  with  the  browser. 

Copernicus  command  -  create  applet  outside  the  Ptolemy  tree. 

Usually,  one  wants  to  put  an  applet  on  a  website.  Ptolemy  applets  require  jar  files  for  the  runtime 
environment,  so  the  applet  code  generator  will  copy  the  necessary  jar  files  if  the  value  of  the  ptHUser- 
Directory  parameter  is  outside  the  $PTII  directory. 

1 .  If  you  built  Ptolemy  II  from  source,  generate  Ptolemy  II  jar  files  by  running 

cd  $  PTI I 
make  install 

2.  Create  the  target  directory: 

mkdir  c : / tmp/pt I I applet /Butterfly 

3.  Invoke  copemicus: 

cd  $PTII/ptolemy/domains/ sdf /demo/Butterf ly 

$PTI I /bin/copernicus  -codeGenerator  applet  -ptl IUserDirectory  \ 
c : /tmp/ptl Iapplet  -targetPath  Butterfly  Butterfly . xml 

Note  that  the  copemicus  command  should  be  typed  in  on  one  line. 

Applet  code  generator  GUI  -  create  applet  outside  the  Ptolemy  tree. 

If  you  would  like  to  generate  an  applet  in  a  directory  outside  of  the  Ptolemy  tree  using  the  experi¬ 
mental  code  generation  GUI,  follow  these  steps: 

1.  If  you  built  Ptolemy  II  from  source,  generate  Ptolemy  II  jar  files  by  running 

cd  $  PTI I 
make  install 

2.  Create  the  target  directory: 

mkdir  c : / tmp/ptl I applet /Butterfly 

3.  Open  up  the  SDF  Butterfly  Model  at  $PTII/ptolemy/domains/sdf/demo/Butterfly/Butterfly.xml 

4.  Select  View  ->  Code  Generator 

5.  Change  the  CodeGenerator  combo  box  from  java  to  applet 

6.  Change  the  ptHUserDirectory  to  the  directory  where  you  would  like  the  applet  to  be  created,  for 
example 

c : /tmp/ptapplet 

Note  that  the  directory  must  already  exist.  If  it  does  not  exist,  then  the  default  directory  will 
automatically  be  used. 

7.  Change  the  targetPath  to  the  string 

$modelName 

8.  Change  the  modelName  parameter  to 

Butterfly 

9.  Hit  the  Parameters  button,  which  will  update  the  parameters  and  display  their  values. 

10.  Hit  the  Generate  Button 

11.  The  code  generator  will  invoke  an  separate  java  process  that  generates  an  applet  and  then  invokes 
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the  browser  on  the  generated  HTML  code. 

9.4.2  Applet  Limitations 

Under  Web  Start,  you  may  need  to  add  classes  to  the  necessaryClasses  parameter  so  that  the  neces- 
saryClassPath  parameter  will  get  updated  with  the  appropriate  jar  files  and  passed  to  the  subprocess 
that  invokes  the  applet  code  generator.  The  reason  this  is  necessary  is  because  Web  Start  is  invoked 
using  a  special  class  loader  that  accesses  separate  jar  files  in  the  Web  Start  cache.  The  applet  code  gen¬ 
erator  does  not  have  direct  access  to  the  Web  Start  class  loader,  so  we  tell  it  what  classes  we  need  so 
that  they  can  be  added  to  the  class  path. 

•  It  would  be  nice  if  the  applet  code  generator  would  bundle  up  the  necessary  class  files  in  a  single 
jar  file  so  that  it  was  easier  to  install  an  applet. 

•  The  applet  code  generator  could  use  tree  shaking  to  create  a  much  smaller  jar  file  that  contains 
only  the  classes  that  are  used.  One  issue  is  that  the  user  would  need  to  exercise  the  applet  by  invok¬ 
ing  all  the  features  of  the  GUI,  such  as  the  plot  format  window. 

•  The  applet  code  generator  should  grab  the  top  level  text  annotations  from  the  MoML  file  and  use 
them  as  comments. 
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